Applies To:
Show Versions
BIG-IP AAM
- 13.1.0, 13.0.1, 13.0.0, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0, 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
BIG-IP APM
- 13.1.0, 13.0.1, 13.0.0, 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0, 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
BIG-IP GTM
- 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
BIG-IP Link Controller
- 13.1.0, 13.0.1, 13.0.0, 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0, 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
BIG-IP LTM
- 13.1.0, 13.0.1, 13.0.0, 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0, 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
BIG-IP DNS
- 13.1.0, 13.0.1, 13.0.0, 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0
BIG-IP ASM
- 13.1.0, 13.0.1, 13.0.0, 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0, 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1, 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
About the iApps template framework
An iApps template has four sections; macro, implementation, presentation, and help. You can view and edit each section with the system's Template Properties screen or with a text editor. If you choose to use an editor, you might find it helpful to see the structure of an empty template as shown here.
sys application template f5.template_name { actions { definition { html-help { <!-- insert html help text --> } implementation { tmsh::create cli alias shared f5.template_name command list } macro { <% #insert text and macro syntax here %> } presentation { # insert apl script } role-acl none run-as none } }Help section
The help section, written in HTML, can provide users with more details about the template.
Macro section
The macro section provides template developers with the ability to develop macros that create objects, and then associate them with iRules.
Implementation section
The implementation section contains the tmsh and Tcl code that performs the actions of the template on the BIG-IP system.
Presentation section
The presentation section contains the application presentation language (APL) that is used by the BIG-IP system to create the template's graphical user interface (GUI).
About template design considerations
Well-designed, easy-to-use templates should be the goal of all iApps template authors.
A complex presentation section can frustrate users and generate more support questions and comments for you, the template author. Here are some basic design considerations your template should follow:
- Use a question and answer format.
- Be simple.
- Be clear.
- Be complete.
- Be understandable.
- Follow established conventions.
About application reentrancy
Application reentrancy, describes the process of making revisions to an application service by revising the design template entries that you used to create it. When you select an application service and then click Reconfigure, you can change the entries on the design template that defines that application service. If you make changes to an application service that results in a new configuration, a mark-and-sweep process transforms the old configuration to this new configuration.
- iApps service object
- Stores the values associated with template inputs
- Mark-and-sweep
- On reentrancy, tmsh create is changed to tmsh modify. Untouched objects are deleted in the sweep.
About the macro section
The macro section of an iApps template allows template developers to create macro templates. These templates produce generic text that can be used as iRules. Using macros in this fashion makes it very straightforward to produce iRules that your users can easily customize with their unique input while maintaining syntactical accuracy and consistency.
When macros are used with iApps templates, the iApps user customizes the iRule simply by responding to simple questions. These responses are then used to populate the macro variables using a tmsh command (TMSH::Macro_expand).
The iApps developer can use the presentation section of the iApps template to make it very straightforward for end users unfamiliar with Tcl code to use and customize iRules. The graphical user interface (GUI) displays questions related to the customizable sections of the iRule that the developer specified in the presentation section of the iApps template. Users can then make simple modifications to create high performance, custom iRules. The resulting iRules are less error prone, and easier to deploy and provide the benefit of fully re-entrant iApps.
Built into the macro syntax is the ability to include implicit or explicit debug statements in the iRules text. These statements can provide iRules developers an excellent mechanism for adding troubleshooting support to their iRules without incurring a runtime cost when the iRules are in production.
For example, consider a template that requests responses for IP addresses and pool names. You create a macro file that contains a list of addresses and pool names, and distribute that to your users; the values will populate the template when the iApps template runs. Users can revise the macro file with entries appropriate for their topology.
Syntax Example
This sample iRule includes macro parameters set up to be populated at runtime.
when HTTP_REQUEST { if { [HTTP::uri] starts_with "/foobar" } { switch -glob [HTTP::uri] { "*[0-9].jpg" { pool numbers_pool } default { if { [string length [substr [HTTP::uri] 0 "?"]] > 0 } { HTTP::respond 200 content "<html><head><title>Where's the number?</title></head></body><h1>Where's the number?</h1></body></html>" } } } } } when HTTP_RESPONSE { if { [HTTP::header Content-Length] > 100 } { log local0. "too much data requested." drop } }This sample illustrates the same iRule, after the parameters have been populated using the macro syntax.
when HTTP_REQUEST { if { [HTTP::uri] starts_with "<%=$url_prefix%>" } { switch -glob [HTTP::uri] { "<%=$glob_pattern%>" { pool <%=$matched_pool%> } default { if { [string length [substr [HTTP::uri] 0 "?"]] > 0 } { HTTP::respond 200 content "<html><head><title><%=$html_title%></title></head></body><h1><%=html_message%></h1></body></html>" } } } } } when HTTP_RESPONSE { if { [HTTP::header Content-Length] > <%=$max_content_length%> } { log local0. "too much data requested." drop } }Macro delimiter syntax
The delimiters for macro parameters are defined in the table.
| Delimiter/Command | Name | Description |
|---|---|---|
| %< | Code to Evaluate | The beginning of an expansion code block. |
| <%= | Evaluate and Output | The beginning of an expansion code block. Spool the output after evaluating. |
| <%D[0-9][0-9] | Debugging/Logging Code | The beginning of a debug/logging code block with the debug threshold set to 0 through 99. |
| %> | Close Code/Output Block | The end of the current block (applies to all delimiter types). |
| <%D[0-9][0-9]= | Debugging/Logging Output | The beginning of an debug expansion code block. Spool the output after evaluating. |
About the implementation section
The implementation section of an iApps template contains the executable code that processes the elements of the presentation section. Template authors must be familiar with Tcl and tmsh scripting in order to write implementations.
About the presentation section
iApps templates use the application presentation language to create application-specific user interfaces in the BIG-IP Configuration utility. Application presentation language code is parsed when a template is selected for use in an application service. When the template is updated, the system also checks the syntax of the code.
About the iApps application presentation language
The iApps application presentation language defines the user interface in the presentation section of an iApps template. The language describes what questions to ask, how the questions are presented (input field verses a pull-down list, for example), and the names of the variables used to store the values of the user entries. It consists of a set of primitive form elements, a set of grouping and organization constructs, methods for hiding or displaying portions of the form based on the values of other portions (optional), and a method to associate various form elements (text) with text that users can read.
About template localization
Text strings in an iApp template can be localized by including localized text stings identified with ISO 639-1 language codes. The text string for a supported locale is selected at run time based on the requesting browser's locale preference. If a string for that locale is not included, the default text string is used.
About template double-byte character support
For international iApps template audiences, the application presentation language text and html commands support Unicode double-byte characters. Using double-byte characters with any other Application Presentation Language (APL) commands might produce unpredictable results.
About application presentation language elements
Application presentation language elements are the graphics building blocks of the presentation section. The iApps application presentation language uses the following elements to create the user interface for template users.
- string
- password
- choice
- editchoice
- multichoice
- table
- row
- message
- section
- optional
- text definitions
- include
- define
string
The string element is the most basic element where a user may enter a single value.
Properties
| Property | Description |
|---|---|
| default | The default value presented if no value was previously entered. This can be a string or a Tcl expression. |
| display | Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge. |
| required | If this property is displayed, the user must provide a valid value. |
| validator | Tells the renderer what type of data is valid. If input is not valid, the user is returned to the template screen that has a red error message next to the field in question. Validators include FQDN, IpOrFqdn, IpAddress, NonNegativeNumber, Number, and PortNumber |
Syntax Example
string user_name required string port default "80" display "small" validator "PortNumber"password
The password element is similar to a string element, except the contents are obscured to protect the data.
Properties
| Property | Description |
|---|---|
| display | Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge. |
| required | If this property is displayed, the user must provide a valid value. |
Syntax Example
password passwd requiredchoice
The choice element presents a list of options where only one item can be selected.
Properties
| Property | Description |
|---|---|
| choices | Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression. |
| default | The default value presented if no value was previously entered. This can be a string or a Tcl expression. |
| display | Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge. |
Syntax Examples
choice pools tcl { tmsh::run_proc utils:get_items ltm pool } choice yesno default "no" {"yes", "no"} choice load_balance_method { "Round Robin" => "round-robin", "Least Connections" => "least-connections-memeber", "Ratio" => "ratio-member" }editchoice
The editchoice element presents multiple choices that users can select, and allows the user to enter a new value if the default choices are not acceptable.
Properties
| Property | Description |
|---|---|
| choices | Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression. |
| default | The default value presented if no value was previously entered. This can be a string or a Tcl expression. |
| display | Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge. |
Syntax Example
editchoice port default "80" {"* All Services" => "*", "HTTP" => "80", "HTTPS" =>"443"}multichoice
Use the multichoice element to allow the user to select multiple items from the available choices.
Properties
| Property | Description |
|---|---|
| choices | Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression. |
| default | The default value presented if no value was previously entered. This can be a string or a Tcl expression. |
| display | Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge. |
Syntax Example
multichoice your_string default {"Choice1", "Choice3"} {"Choice1", "Choice2", "Choice3"}table
The table element can have items added to it, with each item containing multiple pieces of information. Each element added as a child of the table element defines the columns of the table. While the string and choice elements give the ability to set scalar types, table provides the ability to set list types.
Syntax Example
table servers { string address choice port {"80", "443"} }row
You can also think of the row element as a single-row table, and each element that is added as a child of the table element defines the columns of the row.
Syntax Example
your_row seven { string bar1 string bar2}message
The message element adds an extra text message within a section.
Syntax Example
message mymsg "This is my message to you."section
The section element is the topmost hierarchical layout element. The primary function of this element is to group related sub-elements together.
Syntax Example
section ssl_questions { choice ssl_enabled { "true", "false" } }define
The define element allows the creation of user-defined types created out of existing types. The defined type can then be used multiple times independently. This is especially useful in conjunction with the include element because types can be defined in the included application presentation language script, and then used where necessary in the template.
Syntax Example
define choice boolean_question {"True", "False"} section basic { boolean use_ssl }define group type
The built-in grouptype for define allow the you to group multiple elements together into a single defined type so that it can be reused, but will not visually group the elements like "section" does. .
| Usage considerations | Details |
|---|---|
| Restricted use | The group type can only be used as part of a define. |
| Transparent for parent/child type checking | You cannot have a top-level string; it must be inside of a section. When the traversal type checks are made, the group element is ignored and the parent is compared with the top-level elements in the group. |
| No text association | The group element is not allowed to have text associated with it. |
Syntax Example
sys application apl-script f5.apl_common { script { define group snatpool { noyes use_snat optional ( use_snat == "No" ) { noyes need_snatpool optional ( need_snatpool == "Yes" ) { table snatpool_members { string addr required validator "IpAddress" } } } } } } sys application template f5.http { presentation { section basic { ... snatpool snat } text { basic.snat.use_snat "Do the HTTP servers have a route back to application clients via this BIG-IP system?" basic.snat.need_snatpool "Will you have more than 64,000 connections at one time? If so, you will need to enter at least one IP address for each 64,000 connections. " basic.snat.snatpool_members "Enter IP addresses that can be used for a SNAT pool. Enter one IP address for each 64,000 connections " basic.snat.snatpool_members.addr "Address: " } } }optional
The optional element allows application variables to be hidden or shown based on the state of other application variable. The syntax for the optional element is: optional (<expr>) { <contents...> }. Visibility of optional elements is re-evaluated any time the value of an element changes. With optional, you can use only elements that have a value like string or choice.
Syntax Example
In this example, the optional_question string should be shown only if use_ssl is set to "True"
include
The include element copies the referenced content of the application presentation language script into the current document.
Properties
None.
Syntax Example
include "com.f5.apl.common"text
The text element lets you define the text labels and questions for sections, elements, table, or row sub-elements. The syntax for the text element is: text { <section, element, table, or row>.<string name> <"string contents in parenthesis"> }.
Syntax Example
In this example, the text strings contain the template's "edit" section's questions.
section edit { string addr string port } Text { edit “The EDIT section” edit.addr “What IP address do you want for the EDIT virtual server?” edit.port “What port should the EDIT virtual server answer on?” }Dynamic data binding using Tcl expressions
You can use Tcl expressions to dynamically generate default values or an available-choices list at run time. Tcl expressions can retrieve information from the mcpd service and process the data as needed.
After a Tcl script is run, the returned data can be processed into discrete items separated by a new line (\n). Next, split the items by tabs (\t) into display and value segments that represent what the user sees, and what is saved by the mcpd, respectively. Without a tab to split the items, the display is the same as the value.
For example, if a Tcl expression for a choice element returns disp1\t val1\n disp2\t val2, then the list of items presented to the user would be disp1 and disp2.
The following example creates a choice that presents a list of LTMpool names. Note how the tmsh commands are used to retrieve the data.
section my { choice pools tcl { set objs [tmsh::get_config ltm pool] foreach obj $objs { append results [tmsh::get_name $obj] append results "\n" } return $results } }About disabled Tcl commands
When you use iApps to create your own templates from scratch, along with tmsh, you also use Tool Command Language (Tcl) for most of the basic instructions. Because a subset of Tcl commands is disabled from use with iApps templates, you should avoid using these when creating or editing iApps templates.
The Tcl commands that are disabled for iApps template use are:
| after | auto_execok | auto_import |
| auto_load | auto_mkindex | auto_mkindex_old |
| auto_qualify | auto_reset | bgerror |
| cd | close | eof |
| exec | exit | fblocked |
| fconfigure | fcopy | file |
| fileevent | filename | flush |
| gets | glob | http |
| interp | load | memory |
| namespace | open | package |
| pid | pkg::create | pkg_mkIndex |
| proc | pwd | rename |
| seek | socket | source |
| tcl_findLibrary | tell | unknown |
| update | uplevel | upvar |
| vwait |
About presentation section usage recommendations and limitations
The iApps application presentation language has the following usage recommendations and limitations. Follow the recommendations and avoid the limitations to ensure that the system will accept and run your template.
| Recommendation or limitation | Detail |
|---|---|
| Forward definition order | Variables exist only if they have been defined earlier in the template. Specifically, you can create an optional section that displays its contents based on a field above it in the template, but not based on a field that exists below it in the template. |
| No nested sections or tables | The section and table elements do not function correctly if they are embedded in other APL elements. |
| Optionals inside tables must depend on elements outside the table | iApps cannot locate variables inside a template's table, so they must be located outside the APL table element structure. |
About layout elements
Layout elements do not have a value or define a variable. Their primary function is to give hints to the renderer on how the children of the element should be displayed. The layout elements also affect the variable name for the element. When referencing a specific variable within the application presentation language, such as within an expression, then the fully-qualified dotted name is used. For example, if a string called string is contained within a section, my, then the full name would be my.string.
About element validators
Validators are used on certain elements to define what user input is allowable. The BIG-IP system always has the final say on what is allowed, but if a validator value is given to the Configuration utility, it can present the user with a more useful error message about the location of the error.
| Validator | Accepts |
|---|---|
| FQDN | Domain name (RFC 1034) |
| IpOrFqdn | ipv4, ipv6 or domain name (explicitly disallow "*") |
| IpAddress | "*", ipv4 or ipv6 |
| NonNegativeNumber | Integer >=0 |
| Number | Any integer |
| PortNumber | "*" or int value 0-65535 (inclusive) |
The following is an example of a validator that restricts text box input to a valid port number.
string port default "*" validator "portnumber"About the help section
The help section of an iApps template contains HTML help text that template users can access in the BIG-IP Configuration utility under the Help tab. Template authors can supply as little or as much help content as needed. F5 Networks encourages all template authors to provide at least a minimum amount of help.
HTML tags supported in the template help section
An iApps template's help section supports only the HTML tags listed in the following table. Templates containing HTML tags that are not listed in the table generate an error message when an application service tries to use them.
| HTML tag | Function |
|---|---|
| <b> | Defines bold text |
| <blockquote> | Defines a long quotation |
| <br /> | Defines a single line break |
| <code> | Defines computer code text |
| <dd> | Defines a description of a term in a definition list |
| <dl> | Defines a definition list |
| <dt> | Defines a term (an item) in a definition list |
| <em> | Defines emphasized text |
| <h1> to <h6> | Defines HTML headings |
| <i> | Defines italic text |
| <li> | Defines a list item |
| <ol> | Defines an ordered list |
| <p> | Defines a paragraph |
| <pre> | Defines preformatted text |
| <small> | Defines small text |
| <strike> | Defines strikethrough text |
| <strong> | Defines strong text |
| <sub> | Defines subscripted text |
| <sup> | Defines superscripted text |
| <u> | Defines underlined text |
| <ul> | Defines an unordered list |
| <!--...--> | Defines a comment |
About the role-acl property
The role-acl property restricts user access to application services. Besides using the standard user roles to control access to application services, you can further restrict access by setting the role-acl property on the template used for an application service. For example, if you want only administrators to manage the application services, then you set the role-acl property to just admin.
The role-acl property exists at the same hierarchal level in the template as the template sections, as shown below. The role-acl property can only be edited using a text editor because it is not visible in the Configuration utility.
sys application template f5.template_name { actions { definition { html-help { <HTML help definition goes here> } implementation { <Back-end TCL and TMSH code goes here> } presentation { <APL GUI code goes here> } role-acl { admin manager resource-admin } } } }The role-acl property is also useful if a template creates objects that the user role is not able to create. For example, the application editor role is not allowed to create pools, so if your template creates pools, then you should set the role-acl property so that the user gets a more meaningful error message.
