Fortinet black logo

Handbook

Using scripts

Using predefined scripts and commands

You can use scripts to perform actions that are not supported by the current built-in feature set. Scripts enable you to use predefined script commands and variables to manipulate HTTP requests and responses, redirection, or select a content route.

Predefined scripts and commands describes FortiADC's predefined scripts and commands that you can copy and customize.

Predefined scripts and commands

Predefined script/command Usage

AES_DIGEST_SIGN_2F_COMMANDS

Demonstrate how to use AES to encryption/decryption data and some tools to generate the digest.

AUTH_COOKIE_BAKE

Allows you to retrieve the baked cookie and edit the cookie content.

AUTH_EVENTS_n_COMMANDS

Used to get the information from authentication process.

CLASS_SEARCH_n_MATCH Demonstrates how to use the class_match and class_search utility function.
COMPARE_IP_ADDR_2_ADDR_GROUP_DEMO

Compares an IP address to an address group to determine if the IP address is included in the specified IP group. For example ,192.168.1.2 is included in 192.168.1.0/24.

Note: Do NOT use this script "as is". Instead, copy it and customize the IP address and the IP address group.

CONTENT_ROUTING_by_URI Routes to a pool member based on URI string matches. You should not use this script as is. Instead, copy it and customize the URI string matches and pool member names.
CONTENT_ROUTING_by_X_FORWARDED_FOR Routes to a pool member based on IP address in the X-Forwarded-For header. You should not use this script as is. Instead, copy it and customize the X-Fowarded-For header values and pool member names.

COOKIE_COMMANDS

Demonstrate the cookie command to get the whole cookie in a table and how to remove/insert/set the cookie attribute.

COOKIE_COMMANDS_USAGE

Demonstrate the sub-function to handle the cookie attribute "SameSite" and others.

COOKIE_CRYPTO_COMMANDS

Used to perform cookie encryption/decryption on behalf of the real server.

CUSTOMIZE_AUTH_KEY

Demonstrate how to customize the crypto key for authentication cookie.

GENERAL_REDIRECT_DEMO

Redirects requests to a URL with user-defined code and cookie.

Note: Do NOT use this script "as is". Instead, copy and customize the code, URL, and cookie.

GEOIP_UTILITY

Used to fetch the GEO information country and possible province name of an IP address.

HTTP_2_HTTPS_REDIRECTION Redirects requests to the HTTPS site. You can use this script without changes.
HTTP_2_HTTPS_REDIRECTION_FULL_URL

Redirects requests to the specified HTTPS URL.

Note: This script can be used directly, without making any change.

HTTP_DATA_FETCH_SET_DEMO

Collects data in HTTP request body or HTTP response body. In HTTP_REQUEST or HTTP_RESPONSE, you could collect specified size data with “size” in collect().In HTTP_DATA_REQUEST or HTTP_DATA_RESPONSE. You could print the data use “content”, calculate data length with “size”, and rewrite the data with “set”.

Note: Do NOT use this script "as is". Instead, copy it and manipulate the collected data.

HTTP_DATA_FIND_REMOVE_REPLACE_DEMO

Finds a specified string, removes a specified string, or replaces a specified string to new content in HTTP data.

Note: Do NOT use this script "as is". Instead, copy it and manipulate the collected data.

INSERT_RANDOM_MESSAGE_ID_DEMO

Inserts a 32-bit hex string into the HTTP header with a parameter “Message-ID”.

Note: You can use the script directly, without making any change.

IP_COMMANDS

Used to get various types IP Address and port number between client and server side.

MANAGEMENT_COMMANDS

Allow you to disable/enable rest of the events from executing.

MULTIPLE_SCRIPT_CONTROL_DEMO_1

Uses demo_1 and demo_2 script to show how multiple scripts work. Demo_1 with priority 12 has a higher priority.

Note: You could enable or disable other events. Do NOT use this script "as is". Instead, copy it and customize the operation.

MULTIPLE_SCRIPT_CONTROL_DEMO_2

Uses demo_1 and demo_2 script to show how multiple scripts work. Demo_2 with priority 24 has a lower priority.

Note: You could enable or disable other events. Do NOT use this script "as is". Instead, copy it and customize the operation.

OPTIONAL_CLIENT_AUTHENTICATION

Performs optional client authentication.

Note: Before using this script, you must have the following four parameters configured in the client-ssl-profile:

  • client-certificate-verify—Set to the verify you'd like to use to verify the client certificate.
  • client-certificate-verify-option—Set to optional
  • ssl-session-cache-flag—Disable.
  • use-tls-tickets—Disable.

PERSIST_COMMANDS

Demonstrates how to use persist commands and event. Event PERSISTENCE is triggered when FADC receive the HTTP REQ and ready to dispatch to real server.

You can set the entry in PERSISTENCE, then look up it in POST_PERSIST.

FADC will dispatch to dedicate server according to your entry set in PERSISTENCE if this session haven't assign real server before.

RAM_CACHING_COMMANDS

Demonstrate how to use script to do RAM caching.

FADC script allows user to control RAM caching behaviors and check the caching status.

Note: make sure RAM caching configuration is selected in HTTP or HTTPS profile.

RAM_CACHING_DYNAMIC

Demonstrate how to use script to do dynamic RAM caching.

Note: Dynamic caching is identified by a configured ID. Make sure RAM caching configuration is selected in HTTP or HTTPS profile.

RAM_CACHING_GROUPING

Demonstrate how to create multiple variations based on client IP address. The sort of grouping applies to both regular caching and dynamic caching.

Note: make sure RAM caching configuration is selected in HTTP or HTTPS profile.

REDIRECTION_by_STATUS_CODE

Redirects requests based on the status code of server HTTP response (for example, a redirect to the mobile version of a site). Do NOT use this script "as is". Instead, copy it and customize the condition in the server HTTP response status code and the URL values.

REDIRECTION_by_USER_AGENT Redirects requests based on User Agent (for example, a redirect to the mobile version of a site). You should not use this script as is. Instead, copy it and customize the User Agent and URL values.
REWRITE_HOST_n_PATH Rewrites the host and path in the HTTP request, for example, if the site is reorganized. You should not use this script as is. Instead, copy it and customize the "old" and "new" hostnames and paths.
REWRITE_HTTP_2_HTTPS_in_LOCATION

Rewrites HTTP location to HTTPS, for example, rewrite “Location:http://www.example.com” to “Location:https://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTP_2_HTTPS_in_REFERER

Rewrites HTTP referer to HTTPS, for example, rewrite “Referer: http://www.example.com” to “Referer: https://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTPS_2_HTTP_in_LOCATION

Rewrites HTTPS location to HTTP, for example, rewrite “Location:https://www.example.com” to “Location:http://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTPS_2_HTTP_in_REFERER

Rewrites HTTPS referer to HTTP, for example, rewrite “Referer: https://www.example.com” to “Referer: http://www.example.com”.

Note: You can use the script directly, without making any change.

SNAT_COMMANDS

Allows you to overwrite client source address to a specific IP for certain clients, also support IPv4toIPv6 or IPv6toIPv4 type.

Note: Make sure the flag SOURCE ADDRESS is selected in the HTTP or HTTPS type of profile.

SOCKOPT_COMMAND_USAGE

Allows user to customize the TCP_send buffer and TCP_receive buffer size.

SPECIAL_CHARACTERS_HANDLING_DEMO Shows how to use those "magic characters" which have special meanings when used in a certain pattern. The magic characters are ( ) . % + - * ? [ ] ^ $

SSL_EVENTS_n_COMMANDS

Demonstrate how to fetch the SSL certificate information and some of the SSL connection parameters between server and client side.

TCP_EVENTS_n_COMMANDS

Demonstrate how to reject a TCP connection from a client in TCP_ACCEPTED event.

TWO_STEP_VERIFICATION

Demonstrate how to perform 2-Step Verification using FortiToken. One needs have authentication policy configured and selected in a virtual-server.

TWO_STEP_VERIFICATION_2_NEW

Demonstrate how to perform 2-Step Verification using FortiToken for the second authentication group.

TWO_STEP_VERIFICATION_2_SAME

Demonstrate how to perform 2-Step Verification for the second authentication group using the same token group.

TWO_STEP_VERIFICATION_CHANGE_KEY

Demonstrate how to change the AES key and its size for stored token group.

URL_UTILITY_COMMANDS

Demonstrate how to use those url tools to encode/decode/parser/compare.

USE_REQUEST_HEADERS_in_OTHER_EVENTS

Stores a request header value in an event and uses it in other events. For example, you can store a URL in a request event, and use it in a response event.

Note: Do NOT use this script "as is". Instead, copy it and customize the content you want to store, use collect() in HTTP_REQUEST to trigger HTTP_DATA_REQUEST,or use collect() in HTTP_ RESPONSE to trigger HTTP_DATA_ RESPONSE.

UTILITY_FUNCTIONS_DEMO

Demonstrates how to use the basic string operations and random number/alphabet, time, MD5, SHA1, SHA2, BASE64, BASE32, table to string conversion, network to host conversion utility function

Commands

AUTH_EVENTS_n_COMMANDS

Lists the auth event and commands

COOKIE_COMMANDS Lists the two cookie commands and shows how to use them.
IP_COMMANDS Lists the IP commands and shows how to use them.
MANAGEMENT_COMMANDS Lists the management commands and shows how to use them.

PERSIST_COMMANDS

Lists the persist event and commands

RAM_CACHING_COMMANDS

Lists the RAM caching event and commands

SSL_EVENTS_n_COMMANDS Lists the SSL events and commands.
TCP_EVENTS_n_COMMANDS Lists the TCP events and commands.

You can type or paste the script content into the configuration page. After you have created a script configuration object, you can specify it in a virtual server configuration.

Before you begin:

  • Create a script. See Appendix C: Scripts.
  • You must have Read-Write permission for System settings.

The following paragraphs show how to:

Create a script object

To create a script configuration object:
  1. Go to Server Load Balance > Scripting.
  2. Click Create New to display the configuration editor.
  3. Complete the configuration as described in Script configuration.
  4. Save the configuration.

Script configuration

Settings Guidelines

Name

Unique group name. Valid characters are A-Z, a-z, 0-9, _, and -. No spaces.

After you initially save the configuration, you cannot edit the name.

Input

Type or paste the script.

Note: If you want the script to be part of a big multiple script and have it executed in a certain order, be sure to set its priority. For more information, see Support for multiple scripts.

Import a script

To import a script:

  1. Click Import
  2. Click Choose File to browse for the script file.
  3. Click Save.

Export a script

To export a script:

  1. Select the script of interest.
  2. Click Export.

Delete a script

To delete a script:

  1. Select the script of interest.
  2. Click Delete.

Linking multiple scripts to the same virtual server

FortiADC supports the use of a single script file containing multiple scripts and applies them to a single virtual server in one execution. Different scripts can contain the same event. You can specify the priority for each event in each script file to control the sequence in which multiple scripts are executed or let the system to execute the individual scripts in the order they are presented in the multi-script file.

For the current release, you can add up to 16 individual scripts to create a big multi-script file.

If you'd like to, you can disable the processing of the rest of the scripts (e.g., you can disable the processing of the remaining scripts in the list in a script), and even totally disable the processing of a certain event (e.g., you can disable processing the HTTP RESPONSE event in a HTTP REQUEST script). FortiADC also supports multiple calls of HTTP:redirect(), HTTP:redirect_with_cookie(), LB:routing(), and HTTP:close() functions such that the final one prevails.

In practice, rather than building one big complicated script containing all the required logic, it might be more useful to break it down into smaller functional pieces in the form of individual scripts. This is because executing multiple scripts at the same time is more efficient than running them separately, one at a time. Also, breaking down a giant script into multiple small individual scripts makes it more flexible to apply scripts to different virtual servers because some virtual servers may use some of the scripts while others may use them all. With the small individual scripts at hand, you can simply pick and choose only the scripts you need to assemble a big multi-script file with a set priority for each script and apply them all at once to a virtual server.

Apply multiple scripts shows how to link multiple scripts to a single virtual server from the GUI.

Apply multiple scripts

Setting script priority

Priority in a multi-script is optional, but is highly recommended. When executing a big multiple-script file, care must be taken to avoid conflicting commands among the scripts. You can set the priority for each script using the script editor on FortiADC's GUI. Valid values range from 1 to 1,000, with 500 being the default. The smaller the value, the higher the priority. Below is an example script with a set priority:

when HTTP_REQUEST priority 100 {

LB:routing(“cr1”)

}

To display the priority info in the GUI, you can define one and only one event in each script file, as shown below:

Script 1:

when HTTP_REQUEST priority 500 {

LB:routing(“cr1”)

}

Script 2:

when HTTP_RESPONSE priority 500 {

HTTP:close()

}

Script 3:

when HTTP_REQUEST priority 400 {

LB:routing(“cr2”)

}

Script 4:

when HTTP_RESPONSE priority 600 {

HTTP:close()

}

Individual script files are loaded separately into the Lua stack. A numeric value (starting from 1) is appended to each event (e.g., for HTTP_REQUEST event, there are functions HTTP_REQUST1, HTTP_REQUEST2, and so on so forth).

To support multiple scripts, FortiADC:

  • Supports multiple calls of redirect/routing/close function, making them re-entrant so that the final one prevails. For that purpose, the system checks the behavior of multiple calls across redirect(), close(), and routing(). If redirect() comes first, followed by close(), then close() prevails. If close() comes first, followed by redirect(), then redirect() prevails. If you want to close(), you must disable the event after close().
  • Allows enabling or disabling events. There are times when you may want to disable the processing of the remaining scripts while a multi-script file is being executed, or want to disable processing the response completely. The mechanism serves that purpose.
  • Allows enabling or disabling automatic event-enabling behavior. In the HTTP keep-alive mode, the system by default re-enables HTTP REQUEST and HTTP RESPONSE processing for the next transaction (even if they are disabled in the current transaction using the above enable or disable event mechanism). Now you can disable or enable this automatic enabling behavior.

Script priority shows a sample multi-script with priority information.

Script priority

Compiling principles

  • All individual scripts should be pre-compiled when they are linked to a virtual server, where they can be combined into one big multi-script.
  • For the same event, combine the commands in different scripts according to their priorities and orders.
  • For commands of different priorities, FortiADC processes the high-priority commands first, and then the low-priority ones; for commands of the same priority, it processes them in the order they appear in the combined script.
  • And if you are using multiple scripts with overlapping events for bidirectional traffic, you must ensure that the response traffic traverses the overlapping events in the expected order. By default, the scripts applied to the same virtual server will run in the order in which they are applied, regardless of the direction of traffic flow.
  • For a specified event, you must make sure to avoid the conflict commands in different scripts. For example, if you have multiple scripts applied to the same virtual server and the scripts contain both request and response logic, the default execution order is like this:

but NOT like this:

As shown above, FortiADC cannot control the order in which events in the scripts are executed. The only way to enforce the execution order for response traffic is to use the event priority command, as we have discussed above. When setting the priorities, pay special attention to both request and response flows.

Special notes

When using the multi-script feature, keep the following in mind:

  • The multi-script feature is supported on all FortiADC hardware platforms.
  • Currently, the feature can be applied to layer-2 and Layer-7 virtual servers on HTTP/HTTPS protocol only.
  • Scripts are VDOM-specific, and cannot be shared among different VDOMs.
  • Session tables set up using scripts must be synced through high-availability (HA) configuration.
  • Each multi-script script can contain up to 256 individual scripts, each being no more than 32 kilobytes.

Predefined scripts and commands

The 6.x.x release comes with more predefined scripts and commands. You can view and use these scripts and commands by clicking Server Load Balance > Scripting.

Scripts and predefined commands highlights the functions of these scripts and commands and shows how to use them.

Scripts and predefined commands

Note:

  • UTILITY_FUNCTIONS_DEMO and CLASS_SEARCH_n_MATCH provide various utility commands.
  • MULTIPLE_SCRIPT_CONTROL_DEMO_1 and MULTIPLE_SCRIPT_CONTROL_DEMO_2 show how to use multiple-script support.
  • HTTP_DATA_FIND_REMOVE_REPLACE_DEMO and HTTP_DATA_FETCH_SET_DEMO show how to manipulate HTTP data.
  • SPECIAL_CHARACTERS_HANDLING_DEMO shows how to handle certain special characters.
  • INSERT_RANDOM_MESSAGE_ID_DEMO shows how to generate random message IDs.
  • OPTIONAL_CLIENT_AUTHENTICATION shows how to perform optional client authentication based on a request URL.
  • COMPARE_IP_ADDR_2_ADDR_GROUP_DEMO shows how to perform IP address match.
  • USE_REQUEST_HEADERS_in_OTHER_EVENTS shows how to share information across events.
  • Many more predefined scripts are provided for load balance content routing, HTTP redirection, and HTTP content rewriting.

Using scripts

Using predefined scripts and commands

You can use scripts to perform actions that are not supported by the current built-in feature set. Scripts enable you to use predefined script commands and variables to manipulate HTTP requests and responses, redirection, or select a content route.

Predefined scripts and commands describes FortiADC's predefined scripts and commands that you can copy and customize.

Predefined scripts and commands

Predefined script/command Usage

AES_DIGEST_SIGN_2F_COMMANDS

Demonstrate how to use AES to encryption/decryption data and some tools to generate the digest.

AUTH_COOKIE_BAKE

Allows you to retrieve the baked cookie and edit the cookie content.

AUTH_EVENTS_n_COMMANDS

Used to get the information from authentication process.

CLASS_SEARCH_n_MATCH Demonstrates how to use the class_match and class_search utility function.
COMPARE_IP_ADDR_2_ADDR_GROUP_DEMO

Compares an IP address to an address group to determine if the IP address is included in the specified IP group. For example ,192.168.1.2 is included in 192.168.1.0/24.

Note: Do NOT use this script "as is". Instead, copy it and customize the IP address and the IP address group.

CONTENT_ROUTING_by_URI Routes to a pool member based on URI string matches. You should not use this script as is. Instead, copy it and customize the URI string matches and pool member names.
CONTENT_ROUTING_by_X_FORWARDED_FOR Routes to a pool member based on IP address in the X-Forwarded-For header. You should not use this script as is. Instead, copy it and customize the X-Fowarded-For header values and pool member names.

COOKIE_COMMANDS

Demonstrate the cookie command to get the whole cookie in a table and how to remove/insert/set the cookie attribute.

COOKIE_COMMANDS_USAGE

Demonstrate the sub-function to handle the cookie attribute "SameSite" and others.

COOKIE_CRYPTO_COMMANDS

Used to perform cookie encryption/decryption on behalf of the real server.

CUSTOMIZE_AUTH_KEY

Demonstrate how to customize the crypto key for authentication cookie.

GENERAL_REDIRECT_DEMO

Redirects requests to a URL with user-defined code and cookie.

Note: Do NOT use this script "as is". Instead, copy and customize the code, URL, and cookie.

GEOIP_UTILITY

Used to fetch the GEO information country and possible province name of an IP address.

HTTP_2_HTTPS_REDIRECTION Redirects requests to the HTTPS site. You can use this script without changes.
HTTP_2_HTTPS_REDIRECTION_FULL_URL

Redirects requests to the specified HTTPS URL.

Note: This script can be used directly, without making any change.

HTTP_DATA_FETCH_SET_DEMO

Collects data in HTTP request body or HTTP response body. In HTTP_REQUEST or HTTP_RESPONSE, you could collect specified size data with “size” in collect().In HTTP_DATA_REQUEST or HTTP_DATA_RESPONSE. You could print the data use “content”, calculate data length with “size”, and rewrite the data with “set”.

Note: Do NOT use this script "as is". Instead, copy it and manipulate the collected data.

HTTP_DATA_FIND_REMOVE_REPLACE_DEMO

Finds a specified string, removes a specified string, or replaces a specified string to new content in HTTP data.

Note: Do NOT use this script "as is". Instead, copy it and manipulate the collected data.

INSERT_RANDOM_MESSAGE_ID_DEMO

Inserts a 32-bit hex string into the HTTP header with a parameter “Message-ID”.

Note: You can use the script directly, without making any change.

IP_COMMANDS

Used to get various types IP Address and port number between client and server side.

MANAGEMENT_COMMANDS

Allow you to disable/enable rest of the events from executing.

MULTIPLE_SCRIPT_CONTROL_DEMO_1

Uses demo_1 and demo_2 script to show how multiple scripts work. Demo_1 with priority 12 has a higher priority.

Note: You could enable or disable other events. Do NOT use this script "as is". Instead, copy it and customize the operation.

MULTIPLE_SCRIPT_CONTROL_DEMO_2

Uses demo_1 and demo_2 script to show how multiple scripts work. Demo_2 with priority 24 has a lower priority.

Note: You could enable or disable other events. Do NOT use this script "as is". Instead, copy it and customize the operation.

OPTIONAL_CLIENT_AUTHENTICATION

Performs optional client authentication.

Note: Before using this script, you must have the following four parameters configured in the client-ssl-profile:

  • client-certificate-verify—Set to the verify you'd like to use to verify the client certificate.
  • client-certificate-verify-option—Set to optional
  • ssl-session-cache-flag—Disable.
  • use-tls-tickets—Disable.

PERSIST_COMMANDS

Demonstrates how to use persist commands and event. Event PERSISTENCE is triggered when FADC receive the HTTP REQ and ready to dispatch to real server.

You can set the entry in PERSISTENCE, then look up it in POST_PERSIST.

FADC will dispatch to dedicate server according to your entry set in PERSISTENCE if this session haven't assign real server before.

RAM_CACHING_COMMANDS

Demonstrate how to use script to do RAM caching.

FADC script allows user to control RAM caching behaviors and check the caching status.

Note: make sure RAM caching configuration is selected in HTTP or HTTPS profile.

RAM_CACHING_DYNAMIC

Demonstrate how to use script to do dynamic RAM caching.

Note: Dynamic caching is identified by a configured ID. Make sure RAM caching configuration is selected in HTTP or HTTPS profile.

RAM_CACHING_GROUPING

Demonstrate how to create multiple variations based on client IP address. The sort of grouping applies to both regular caching and dynamic caching.

Note: make sure RAM caching configuration is selected in HTTP or HTTPS profile.

REDIRECTION_by_STATUS_CODE

Redirects requests based on the status code of server HTTP response (for example, a redirect to the mobile version of a site). Do NOT use this script "as is". Instead, copy it and customize the condition in the server HTTP response status code and the URL values.

REDIRECTION_by_USER_AGENT Redirects requests based on User Agent (for example, a redirect to the mobile version of a site). You should not use this script as is. Instead, copy it and customize the User Agent and URL values.
REWRITE_HOST_n_PATH Rewrites the host and path in the HTTP request, for example, if the site is reorganized. You should not use this script as is. Instead, copy it and customize the "old" and "new" hostnames and paths.
REWRITE_HTTP_2_HTTPS_in_LOCATION

Rewrites HTTP location to HTTPS, for example, rewrite “Location:http://www.example.com” to “Location:https://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTP_2_HTTPS_in_REFERER

Rewrites HTTP referer to HTTPS, for example, rewrite “Referer: http://www.example.com” to “Referer: https://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTPS_2_HTTP_in_LOCATION

Rewrites HTTPS location to HTTP, for example, rewrite “Location:https://www.example.com” to “Location:http://www.example.com”.

Note: You can use the script directly, without making any change.

REWRITE_HTTPS_2_HTTP_in_REFERER

Rewrites HTTPS referer to HTTP, for example, rewrite “Referer: https://www.example.com” to “Referer: http://www.example.com”.

Note: You can use the script directly, without making any change.

SNAT_COMMANDS

Allows you to overwrite client source address to a specific IP for certain clients, also support IPv4toIPv6 or IPv6toIPv4 type.

Note: Make sure the flag SOURCE ADDRESS is selected in the HTTP or HTTPS type of profile.

SOCKOPT_COMMAND_USAGE

Allows user to customize the TCP_send buffer and TCP_receive buffer size.

SPECIAL_CHARACTERS_HANDLING_DEMO Shows how to use those "magic characters" which have special meanings when used in a certain pattern. The magic characters are ( ) . % + - * ? [ ] ^ $

SSL_EVENTS_n_COMMANDS

Demonstrate how to fetch the SSL certificate information and some of the SSL connection parameters between server and client side.

TCP_EVENTS_n_COMMANDS

Demonstrate how to reject a TCP connection from a client in TCP_ACCEPTED event.

TWO_STEP_VERIFICATION

Demonstrate how to perform 2-Step Verification using FortiToken. One needs have authentication policy configured and selected in a virtual-server.

TWO_STEP_VERIFICATION_2_NEW

Demonstrate how to perform 2-Step Verification using FortiToken for the second authentication group.

TWO_STEP_VERIFICATION_2_SAME

Demonstrate how to perform 2-Step Verification for the second authentication group using the same token group.

TWO_STEP_VERIFICATION_CHANGE_KEY

Demonstrate how to change the AES key and its size for stored token group.

URL_UTILITY_COMMANDS

Demonstrate how to use those url tools to encode/decode/parser/compare.

USE_REQUEST_HEADERS_in_OTHER_EVENTS

Stores a request header value in an event and uses it in other events. For example, you can store a URL in a request event, and use it in a response event.

Note: Do NOT use this script "as is". Instead, copy it and customize the content you want to store, use collect() in HTTP_REQUEST to trigger HTTP_DATA_REQUEST,or use collect() in HTTP_ RESPONSE to trigger HTTP_DATA_ RESPONSE.

UTILITY_FUNCTIONS_DEMO

Demonstrates how to use the basic string operations and random number/alphabet, time, MD5, SHA1, SHA2, BASE64, BASE32, table to string conversion, network to host conversion utility function

Commands

AUTH_EVENTS_n_COMMANDS

Lists the auth event and commands

COOKIE_COMMANDS Lists the two cookie commands and shows how to use them.
IP_COMMANDS Lists the IP commands and shows how to use them.
MANAGEMENT_COMMANDS Lists the management commands and shows how to use them.

PERSIST_COMMANDS

Lists the persist event and commands

RAM_CACHING_COMMANDS

Lists the RAM caching event and commands

SSL_EVENTS_n_COMMANDS Lists the SSL events and commands.
TCP_EVENTS_n_COMMANDS Lists the TCP events and commands.

You can type or paste the script content into the configuration page. After you have created a script configuration object, you can specify it in a virtual server configuration.

Before you begin:

  • Create a script. See Appendix C: Scripts.
  • You must have Read-Write permission for System settings.

The following paragraphs show how to:

Create a script object

To create a script configuration object:
  1. Go to Server Load Balance > Scripting.
  2. Click Create New to display the configuration editor.
  3. Complete the configuration as described in Script configuration.
  4. Save the configuration.

Script configuration

Settings Guidelines

Name

Unique group name. Valid characters are A-Z, a-z, 0-9, _, and -. No spaces.

After you initially save the configuration, you cannot edit the name.

Input

Type or paste the script.

Note: If you want the script to be part of a big multiple script and have it executed in a certain order, be sure to set its priority. For more information, see Support for multiple scripts.

Import a script

To import a script:

  1. Click Import
  2. Click Choose File to browse for the script file.
  3. Click Save.

Export a script

To export a script:

  1. Select the script of interest.
  2. Click Export.

Delete a script

To delete a script:

  1. Select the script of interest.
  2. Click Delete.

Linking multiple scripts to the same virtual server

FortiADC supports the use of a single script file containing multiple scripts and applies them to a single virtual server in one execution. Different scripts can contain the same event. You can specify the priority for each event in each script file to control the sequence in which multiple scripts are executed or let the system to execute the individual scripts in the order they are presented in the multi-script file.

For the current release, you can add up to 16 individual scripts to create a big multi-script file.

If you'd like to, you can disable the processing of the rest of the scripts (e.g., you can disable the processing of the remaining scripts in the list in a script), and even totally disable the processing of a certain event (e.g., you can disable processing the HTTP RESPONSE event in a HTTP REQUEST script). FortiADC also supports multiple calls of HTTP:redirect(), HTTP:redirect_with_cookie(), LB:routing(), and HTTP:close() functions such that the final one prevails.

In practice, rather than building one big complicated script containing all the required logic, it might be more useful to break it down into smaller functional pieces in the form of individual scripts. This is because executing multiple scripts at the same time is more efficient than running them separately, one at a time. Also, breaking down a giant script into multiple small individual scripts makes it more flexible to apply scripts to different virtual servers because some virtual servers may use some of the scripts while others may use them all. With the small individual scripts at hand, you can simply pick and choose only the scripts you need to assemble a big multi-script file with a set priority for each script and apply them all at once to a virtual server.

Apply multiple scripts shows how to link multiple scripts to a single virtual server from the GUI.

Apply multiple scripts

Setting script priority

Priority in a multi-script is optional, but is highly recommended. When executing a big multiple-script file, care must be taken to avoid conflicting commands among the scripts. You can set the priority for each script using the script editor on FortiADC's GUI. Valid values range from 1 to 1,000, with 500 being the default. The smaller the value, the higher the priority. Below is an example script with a set priority:

when HTTP_REQUEST priority 100 {

LB:routing(“cr1”)

}

To display the priority info in the GUI, you can define one and only one event in each script file, as shown below:

Script 1:

when HTTP_REQUEST priority 500 {

LB:routing(“cr1”)

}

Script 2:

when HTTP_RESPONSE priority 500 {

HTTP:close()

}

Script 3:

when HTTP_REQUEST priority 400 {

LB:routing(“cr2”)

}

Script 4:

when HTTP_RESPONSE priority 600 {

HTTP:close()

}

Individual script files are loaded separately into the Lua stack. A numeric value (starting from 1) is appended to each event (e.g., for HTTP_REQUEST event, there are functions HTTP_REQUST1, HTTP_REQUEST2, and so on so forth).

To support multiple scripts, FortiADC:

  • Supports multiple calls of redirect/routing/close function, making them re-entrant so that the final one prevails. For that purpose, the system checks the behavior of multiple calls across redirect(), close(), and routing(). If redirect() comes first, followed by close(), then close() prevails. If close() comes first, followed by redirect(), then redirect() prevails. If you want to close(), you must disable the event after close().
  • Allows enabling or disabling events. There are times when you may want to disable the processing of the remaining scripts while a multi-script file is being executed, or want to disable processing the response completely. The mechanism serves that purpose.
  • Allows enabling or disabling automatic event-enabling behavior. In the HTTP keep-alive mode, the system by default re-enables HTTP REQUEST and HTTP RESPONSE processing for the next transaction (even if they are disabled in the current transaction using the above enable or disable event mechanism). Now you can disable or enable this automatic enabling behavior.

Script priority shows a sample multi-script with priority information.

Script priority

Compiling principles

  • All individual scripts should be pre-compiled when they are linked to a virtual server, where they can be combined into one big multi-script.
  • For the same event, combine the commands in different scripts according to their priorities and orders.
  • For commands of different priorities, FortiADC processes the high-priority commands first, and then the low-priority ones; for commands of the same priority, it processes them in the order they appear in the combined script.
  • And if you are using multiple scripts with overlapping events for bidirectional traffic, you must ensure that the response traffic traverses the overlapping events in the expected order. By default, the scripts applied to the same virtual server will run in the order in which they are applied, regardless of the direction of traffic flow.
  • For a specified event, you must make sure to avoid the conflict commands in different scripts. For example, if you have multiple scripts applied to the same virtual server and the scripts contain both request and response logic, the default execution order is like this:

but NOT like this:

As shown above, FortiADC cannot control the order in which events in the scripts are executed. The only way to enforce the execution order for response traffic is to use the event priority command, as we have discussed above. When setting the priorities, pay special attention to both request and response flows.

Special notes

When using the multi-script feature, keep the following in mind:

  • The multi-script feature is supported on all FortiADC hardware platforms.
  • Currently, the feature can be applied to layer-2 and Layer-7 virtual servers on HTTP/HTTPS protocol only.
  • Scripts are VDOM-specific, and cannot be shared among different VDOMs.
  • Session tables set up using scripts must be synced through high-availability (HA) configuration.
  • Each multi-script script can contain up to 256 individual scripts, each being no more than 32 kilobytes.

Predefined scripts and commands

The 6.x.x release comes with more predefined scripts and commands. You can view and use these scripts and commands by clicking Server Load Balance > Scripting.

Scripts and predefined commands highlights the functions of these scripts and commands and shows how to use them.

Scripts and predefined commands

Note:

  • UTILITY_FUNCTIONS_DEMO and CLASS_SEARCH_n_MATCH provide various utility commands.
  • MULTIPLE_SCRIPT_CONTROL_DEMO_1 and MULTIPLE_SCRIPT_CONTROL_DEMO_2 show how to use multiple-script support.
  • HTTP_DATA_FIND_REMOVE_REPLACE_DEMO and HTTP_DATA_FETCH_SET_DEMO show how to manipulate HTTP data.
  • SPECIAL_CHARACTERS_HANDLING_DEMO shows how to handle certain special characters.
  • INSERT_RANDOM_MESSAGE_ID_DEMO shows how to generate random message IDs.
  • OPTIONAL_CLIENT_AUTHENTICATION shows how to perform optional client authentication based on a request URL.
  • COMPARE_IP_ADDR_2_ADDR_GROUP_DEMO shows how to perform IP address match.
  • USE_REQUEST_HEADERS_in_OTHER_EVENTS shows how to share information across events.
  • Many more predefined scripts are provided for load balance content routing, HTTP redirection, and HTTP content rewriting.