53-1002445-01 January, 2012 ServerIron ADX OpenScript Programmer’s Guide Supporting Brocade ServerIron ADX version 12.4.
© 2012 Brocade Communications Systems, Inc. All Rights Reserved. Brocade, Brocade Assurance, the B-wing symbol, DCX, Fabric OS, MLX, SAN Health, VCS, and VDX are registered trademarks, and AnyIO, Brocade One, CloudPlex, Effortless Networking, ICX, NET Health, OpenScript, and The Effortless Network are trademarks of Brocade Communications Systems, Inc., in the United States and/or in other countries. Other brands, products, or service names mentioned may be trademarks of their respective owners.
ServerIron ADX Global Server Load Balancing Guideiii 53-1002445-01
ivServerIron ADX Global Server Load Balancing Guide 53-1002445-01
Contents About This Document Supported hardware and software . . . . . . . . . . . . . . . . . . . . . . . . . . vii Document conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Notes, cautions, and danger notices . . . . . . . . . . . . . . . . . . . . . vii Notice to the reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Deleting a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Renaming a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Display script in the script directory . . . . . . . . . . . . . . . . . . . . . . 15 Compiling and binding scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About This Document Supported hardware and software Although many different software and hardware configurations are tested and supported by Brocade Communications Systems, Inc. for 12.4.00 documenting all possible configurations and scenarios is beyond the scope of this document.
NOTE A note provides a tip, guidance or advice, emphasizes important information, or provides a reference to related information. CAUTION A Caution statement alerts you to situations that can be potentially hazardous to you or cause damage to hardware, firmware, software, or data. DANGER A Danger statement indicates conditions or situations that can be potentially lethal or extremely hazardous to you. Safety labels are also attached directly to products to warn of these conditions or situations.
• ServerIron ADX NAT64 Configuration Guide • ServerIron ADX OpenScript API Guide • IronWare MIB Reference Getting technical help or reporting errors Brocade is committed to ensuring that your investment in our products remains cost-effective. If you need assistance, or find errors in the manuals, contact Brocade using one of the following options: Web access The Knowledge Portal (KP) contains the latest version of this guide and other user guides for the product. You can also report errors on the KP.
x ServerIron ADX OpenScript Guide 53-1002445-01
Chapter Overview of OpenScript 1 The Application Delivery environment requires more than simple CLI commands for managing Application traffic. Often, an operator wants to make packet forwarding decisions based on real-time events such as layer-3, layer-4, layer-7 data or server metrics such as current server load statistics. These situations require a more dynamically programmable environment than traditionally offered through built-in CLI commands.
1 Overview of OpenScript Extensibility Perl was selected for the OpenScript platform because it is open and modular which allows new functionality to be added easily. In addition to the support provided by Brocade, CPAN (Comprehensive Perl Archive Network), is one of the largest repositories of free code in the world. If you need a particular type of functionality, chances are there are several options on the CPAN, and there are no fees or ongoing costs for using it.
The OpenScript Engine 1 The OpenScript Engine The OpenScript engine provides the ability for direct interaction with traffic passing through a ServerIron ADX. User-provided, custom logic written in the Perl programming language can use ServerIron ADX monitoring capabilities to observe network traffic between clients and servers and then react to traffic patterns by altering the traffic flows. Figure 1 illustrates the flow of traffic through an OpenScript engine residing on a ServerIron ADX.
1 Using Perl on the ServerIron ADX Architecture of the OpenScript engine Because script parsing is highly CPU-intensive it is performed entirely on the management processor (MP) of the ServerIron ADX. If the compilation succeeds on the MP, the script is downloaded to the application processor (BP) for installation. The BP prepares the script by generating machine byte code and binds it by inlining it in the packet processing path for the virtual server and service. This process is displayed in Figure 2.
Using Perl on the ServerIron ADX TABLE 2 Perl lexical variable scoping on a ServerIron ADXs Lexical Type/object Scope Re-initialized per run Exported to MP Use Data Type Allowed Limit my script Yes No Script local/auto Perl all Script state script No No Script static Perl all Script Conn hash connection No Yes Correlate client & server flows Perl all Script ServerIron ADX OpenScript Guide 53-1002445-01 1 5
1 6 Using Perl on the ServerIron ADX ServerIron ADX OpenScript Guide 53-1002445-01
Chapter 2 OpenScript Fundamentals Overview This following sections of this chapter describe the process of creating a simple script using the Perl-based, OpenScript environment. Structure of a ServerIron ADX Perl script The structure of a Perl script written for OpenScript differs slightly from the standard free-flowing script program usually associated with Perl. In a regular perl script, methods (subs) can be freely defined and invoked from the main body of the script.
2 Structure of a ServerIron ADX Perl script TABLE 3 Application and Protocol Events in ADX scripts Application/ Event Description Protocol UDP SLB 8 Attached Script Method Use On TCP client layer 7 application payload data being available. Only triggered by collect() API TCP_CLIENT_DATA Inspect and transform client side TCP application data. On server initiating a TCP CLOSE. TCP_SERVER_CLOSE Update counters/state. On receiving TCP RESET from server.
Basic anatomy of a script 2 Basic anatomy of a script The basic example script (abc.pl) is designed to exercise access control based on a client’s IP address and a running count of the total number of connections per virtual server port. As displayed, it consists of the following elements: • Declaration Block – Declares the packages being used by the script.
2 Sample scripts Sample scripts The following examples provide two different approaches to creating a script for the same purpose. The first example provides a heavily commented example for high readability and the second is a “power-user” version of the script. It is much more compact with less extensive notation. Both scripts provide for load-balancing using a URL match in an HTTP GET request.
Sample scripts 2 # Power User version # Performs server selection based on URI in # HTTP Request Header use OS_HTTP_Request; use OS_SLB; sub HTTP_REQUEST { # local variable with default server group-id $server = 2; $request = OS_HTTP_REQUEST::get; if ($request->url =~ m/"index.html"/) $server = "RS1"; # $server can hold integer or string values. # Xtension backend does translation.
2 12 Sample scripts ServerIron ADX OpenScript Guide 53-1002445-01
Chapter Managing Scripts on a ServerIron ADX 3 Overview A script can be written with any text editor or using the ServerIron ADX GUI. The ServerIron ADX GUI.process is described in the ServerIron ADX GUI Configuration Guide. Once a script has been written, it must be uploaded to a ServerIron ADX to be compiled and bound to a port. In addition, several operations can be performed on the script and a profile can be defined that sets the environmental variables under which the script will run.
3 Managing scripts Importing and exporting scripts through TFTP You can use the copy tftp command to upload a script to a ServerIron ADX from a TFTP server as shown. ServerIronADX# copy tftp usb0 1.1.1.1 sample.pl sys\dpscript\sample.pl Syntax: copy tftp usb0 sys\dpscript\ The variable is the address of the TFTP server where the script resides. The variable is the filename of the script file.
Compiling and binding scripts 3 Syntax: rename usb0\sys\dpscript\ usb0\sys\dpscript\ The variable is the name of the script file that you want to rename. The variable is the new name that you want to create for the script file. NOTE A script that is currently bound to a VIP port cannot be renamed.
3 Compiling and binding scripts Compiling a script and obtaining output from the performance estimator You can compile a script as a single independent operation through the script compile command. Running this command insures that the compile will be successful and displays the results of the performance estimator.The following example compiles the “slb.pl” script and runs the performance estimator on it. ServerIronADX(config)# script compile slb.
Creating and configuring script profiles 3 The script profile parameter directs the ServerIron ADX to apply the previously configured script profile specified by the variable to the script being bound. If you do not specify a script profile the default script profile values will be used. See “Creating and configuring script profiles” on page 17. Updating an existing script You can update all running instances of a script with the contents a newly updated script of the same name.
3 Creating and configuring script profiles • script restart limit: If a script is having problems during operation or it exceeds limitations set in the profile (either default or configured) it will restart. This option can be configured to limit the number of times that the script will be restarted. Once this limit is reached, the script will be halted and not restarted.
Creating and configuring script profiles 3 ServerIronADX(config)# script-profile sp1 ServerIronADX(config-script-profile-sp1)# memory-high-watermark 80 Are you sure you want to dercres the memory limit from 1048576 to 200000? (yes or no): yes Syntax: [no] memory-high-watermark The variable is the new high-water mark percentage that you want to set. The default value is 90 (%). Using the no parameter before the command returns the memory high-water mark to the default value.
3 Displaying script information ServerIronADX(config-script-profile-sp1)# restart-limit 10 Syntax: [no] restart-limit The variable is the maximum number of times that the script will restart after running into problems. By default a script will restart every time it is halted. This value can be set to any integer. Using the no parameter before the command returns the restart limit to the default value. Enabling script debugging This parameter enables script debugging.
Displaying script information 3 ServerIronADX# show script myscript.pl detail vip1 http Script myscript.
3 ServerIronADX# show script profile sp1 Script profile sp1 ====================================================== Memory limit: 2000000 Memory high water mark: 80% Time out: 1000ms Data collection limit: 50000 Restart Limit: None Debug: off Print Output: syslog Syntax: show script-profile The variable specifies the script profile you want to display the current settings for. TABLE 5 22 Runtime script statistics This field... Displays...
Chapter Script Example 4 Overview The following sections of this chapter describe the entire process of writing a script, copying it to the ServerIron ADX and binding it to a virtual server port Use case This script is created in this example is designed to perform the following action on any SSL or HTTP traffic: • It there is no X-Forwarded-For header, an X-forwarded-For header is added with the client source IP address: e.g. 4.4.4.4 • If a X-Forwarded-For header exists, the source IP address 4.4.4.
4 Copying and binding the script Copying and binding the script The following command copies the script from a TFTP server to the to the ServerIron ADX. ServerIronADX# copy tftp usb0 1.1.1.1 addip.pl sys\dapscript\addip.pl The script is bound to the “vs1” virtual server as shown. ServerIronADX(config)# server virtual vs1 ServerIronADX(config-vs-vs1)# port http script addip.pl Sample ServerIron ADX configuration for use case.
