53-1003244-01 July 2014 Brocade Virtual ADX OpenScript Programmer’s Guide Supporting Brocade Virtual ADX version 03.1.
Copyright © 2014 Brocade Communications Systems, Inc. All Rights Reserved. ADX, AnyIO, Brocade, Brocade Assurance, the B-wing symbol, DCX, Fabric OS, ICX, MLX, MyBrocade, OpenScript, VCS, VDX, and Vyatta are registered trademarks, and HyperEdge, The Effortless Network, and The On-Demand Data Center 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.
Contents Preface Document conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Command syntax conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . v Notes, cautions, and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . .vi Brocade resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Getting technical help . . .
Creating and configuring script profiles. . . . . . . . . . . . . . . . . . . . . . . 16 Creating a script profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Setting the script memory limit. . . . . . . . . . . . . . . . . . . . . . . . . . 17 Setting the script memory high-water mark. . . . . . . . . . . . . . . . 17 Setting the script timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Setting the script data collection limit . . . . . . . . . . . . . . . . . . .
Preface Document conventions This section describes text formatting conventions and important notice formats that may be used in this document. Text formatting The following text formatting conventions may be used in the flow of the text to highlight specific words or phrases.
Command syntax conventions Convention Description bold text Identifies command names, keywords, and command options. italic text Identifies variables. [] Syntax components displayed within square brackets are optional. { x | y |z } A choice of required parameters is enclosed in curly braces separated byvertical bars. You must select one. x|y A vertical bar separates mutually exclusive elements. <> Nonprinting characters, for example, passwords, are enclosed in angle brackets. ...
Brocade resources To get up-to-the-minute information, go to http://my.brocade.com to register at no cost for a user ID and password. Release notes are available at http://my.brocade.com. White papers, online demonstrations, and data sheets are available through the Brocade website at: http://www.brocade.com/products-solutions/products/index.page Select Application Delivery Switches on this page to navigate to the relevant product information.
Document feedback • Brocade Supplemental Support augments your existing OEM support contract, providing direct access to Brocade expertise. For more information, contact Brocade or your OEM. • For questions regarding service levels and response times, contact your OEM/Solution Provider. Document feedback Quality is our first concern at Brocade and we have made every effort to ensure the accuracy and completeness of this document.
Chapter Overview of OpenScript 1 Overview 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 fly. In a multipass Scripting Engine such as Perl, the initial phase involves scanning and parsing the input script to generate an intermediate byte code representation. The final run phase executes the generated byte code by invoking underlying machine operations associated with each node in the parsed byte code tree. Extensibility Perl was selected for the OpenScript platform because it is open and modular which allows new functionality to be added easily.
The OpenScript Engine 1 The OpenScript Engine The OpenScript engine provides the ability for direct interaction with traffic passing through a Brocade Virtual ADX. User-provided, custom logic written in the Perl programming language can use Brocade Virtual 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 Brocade Virtual ADX.
1 Using Perl on the Brocade Virtual ADX Architecture of the OpenScript engine Because script parsing is highly CPU-intensive it is performed entirely on the management processor (MP) of the Brocade Virtual 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.
Using Perl on the Brocade Virtual ADX TABLE 2 1 Perl lexical variable scoping on a Brocade Virtual 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 Brocade Virtual ADX OpenScript Programmer’s Guide 53-1003244-01 5
1 6 Using Perl on the Brocade Virtual ADX Brocade Virtual ADX OpenScript Programmer’s Guide 53-1003244-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 Brocade Virtual 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 Brocade Virtual ADX Perl script TABLE 3 Application or protocol Application and protocol events in ADX scripts (Continued) Event description Attached script method Use On client initiating a TCP CLOSE. TCP_CLIENT_CLOSE Update counters or state. On receiving a TCP client RESET. TCP_CLIENT_RESET Update counters or state. On TCP client Layer 7 application payload data being available. TCP_CLIENT_DATA Inspect and transform client-side TCP application data.
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. • Initialization block – Only evaluated once before the first run of 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 script example The following example is the “power-user” version of the script. It is much more compact with less extensive notation. Example 2: # Power User version # Performs server selection based on URI in # HTTP Request Header use use use use OS_HTTP_Request; OS_SLB; strict; Sub::StrictDecl; sub HTTP_REQUEST { # local variable with default server group-id $server = 2; if (OS_HTTP_REQUEST::url =~ m/"index.
2 12 Sample scripts Brocade Virtual ADX OpenScript Programmer’s Guide 53-1003244-01
Chapter Managing Scripts on a Brocade Virtual ADX 3 Overview A script can be written with any text editor or using the Brocade Virtual ADX GUI. The Brocade Virtual ADX GUI process is described in the Brocade Virtual ADX GUI Configuration Guide. Once a script has been written, it must be uploaded to a Brocade Virtual ADX to be compiled and bound to a port.
3 Managing scripts Managing scripts In addition, the you can manage scripts on the Brocade Virtual ADX as described in the following. • “Deleting a script” • “Renaming a script” • “Display script in the script directory” Deleting a script You can use the del command to delete a script from a Brocade Virtual ADX as shown. VirtualADX# del openscripts/dpscript/sample.pl Syntax: del openscripts/dpscript/script-name The script_name variable is the name of the script file that you want to delete.
Compiling and binding scripts 3 Compiling and binding scripts Once a script has been copied to the Brocade Virtual ADX, you must compile it before it can be run. After the script is compiled, it is ready to run on the Brocade Virtual ADX but it must be bound to a VIP that you want it to operate on. Unless a script is explicitly bound to a VIP it will not effect traffic on the Brocade Virtual ADX.
3 Creating and configuring script profiles Creating and configuring script profiles A script profile sets the environmental variables for any script it is applied to. These variables involve use of memory by the script and behavior during script operation. This is an optional configuration, Where a script profile is not configured, the default values will take effect.
Creating and configuring script profiles 3 The profile-name variable is the name of the profile that you want to create or update. Using the no parameter before the command deletes the named profile. NOTE When an script profile is changed, the updated profile parameters are automatically applied to the virtual ports that it is bound to. Setting the script memory limit This parameter sets the memory limit for any script that is bound to it.
3 Creating and configuring script profiles The milliseconds variable is new watchdog time that you want to set in milliseconds. The default value is 200 (milliseconds). Values can be set from 50 to 1000. Using the no parameter before the command returns the watchdog time to the default value. Setting the script data collection limit This parameter sets the data collection limit for the script in bytes. The script data collection limit is set as shown.
Displaying script information 3 The syslog parameter sets the script to log to a log server, not the local log of the Brocade Virtual ADX (show logging). You must configure a remote server (per the global logging ip-addr command) to receive the log. The syslog server cannot be connected to the management port because script log action is processed by the BP, and the management port is controlled by the MP. The none parameter disables the script from printing.
3 Displaying script information TABLE 4 Run-time script statistics Field Description Virtual Server The virtual server name. Service-Port The service port. Script State The state of the script: Active, Suspended or UpdatePending Last Updated The date and time that the script was last updated. Script Restart The number of times that the script restarted. Total Connections The total connections. Concurrent Connections The number of concurrent connections.
Chapter Script Example 4 Overview The following sections of this chapter describe the entire process of writing a script, copying it to the Brocade Virtual 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 HTTP traffic: • If 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 secure copies the addip.pl script from the /home/test directory on the Linux server 1.1.1.1 to the Brocade Virtual ADX. scp root@1.1.1.1:/home/test/addip.pl /opt/ADX/openscripts/dpscript/addip.pl The script is bound to the “vs1” virtual server as shown. VirtualADX(config)# server virtual vs1 VirtualADX(config-vs-vs1)# port http script addip.pl Sample Brocade Virtual ADX configuration for use case.
