iApp Utility Package

REFERENCE GUIDE

The iapp.1.1.0.tcl utility package contains useful Tcl procedures that you can use when building iApps.

iapp::template

DESCRIPTION
Run common logging tasks during iApp implementation
SYNOPSIS
iapp::template ACTION

DESCRIPTION
iapp::template start sets the iApp’s log-level to the sys scriptd log-level. It writes a timestamp to /var/tmp/scriptd if ACTION is either “start” or “stop” (“end” is equivalent to “stop”). It also defines a global variable for the lengthy list of http content-types as a convenience to template programmers.
EXAMPLES
iapp::template start
iapp::template stop

iapp::is - safely determine if a variable matches given values

SYNOPSIS
iapp::is VARNAME STRING STRING...

DESCRIPTION
iapp::is returns 1 if VARNAME matches any STRING in the argument list. It returns 0 if VARNAME does not match or does not exist. This is especially handy for reading optional-enclosed APL variables, which disappear when the optional condition is not satisfied.
EXAMPLE
iapp::is ::net__route_to_bigip "yes"

iapp::substa - run tcl subst with array wildcard handling

SYNOPSIS
iapp::substa ARRAYNAME

DESCRIPTION
iapp::substa assists with a tcl programming style that replaces long if-then-else chains with compact decision-making arrays. These arrays often have some number of identical outcomes, which may be grouped together as one line in the array using the wildcard index “*”. iapp::substa does not support multiple wildcards or regex matching.
EXAMPLE
set do_snat      [expr { [iapp::is ::net__same_subnet  yes] \
                 || ![iapp::is ::net__route_to_bigip yes] || !$advanced}]
set do_automap   [expr { [iapp::is ::net__snat_type automap] || !$advanced}]
set new_snatpool [iapp::is ::net__snatpool $::CREATE_NEW_ANSWER]

# array keys: $do_snat,$do_automap,$new_snatpool
array set snatpool_arr {
    1,1,1 { snat automap }
    1,1,0 { snat automap }
    1,0,1 { snatpool [iapp::conf create ltm snatpool ${app}_snatpool \
            members replace-all-with \{ [string map \
            {"addr " "" \{ "" \} ""} $::net__snatpool_members] \} ]}
    1,0,0 { snatpool $::net__snatpool }
    *     { snat none }
}

set snat_action [iapp::substa snatpool_arr($do_snat,$do_automap,$new_snat)]

iapp::conf - execute a tmsh command with logging to scriptd

SYNOPSIS
iapp::conf [create|modify|delete] ARGS

DESCRIPTION
iapp::conf passes all ARGS to tmsh, as if executing tmsh at the command line. It caches the command in order to prevent redundant calls, and it logs the command to /var/tmp/scriptd.out, obscuring clear-text passwords in most cases (passwords inside external monitors are one exception).
EXAMPLE
iapp::conf create ltm profile analytics ${app}_analytics \
     defaults-from analytics

iapp::make_safe_password - escape special characters for iApp passwords

SYNOPSIS
iapp::make_safe_password STRING

DESCRIPTION
iapp::make_safe_password packages any instances of the 3 characters ‘ # \ so they are properly received by tmsh when used in passwords.
EXAMPLE
iapp::conf modify ltm monitor http ${app}_monitor password \
    [iapp::make_safe_password $::monitor__passwd]

iapp::tmos_version - compare current software version to supplied value

SYNOPSIS
iapp::tmos_version COMPARATOR VALUE

DESCRIPTION
iapp::tmos_version returns 1 if the comparison returns true, 0 if false, or returns the raw version number if COMPARATOR is not supplied.
EXAMPLE
set use_httpclass [iapp::tmos_version < 11.4]

iapp::get_items - get tmsh configuration values

SYNOPSIS
iapp::get_items [OPTIONS] ARGS

OPTIONS
-exists      returns 0 if query result is errored or empty, otherwise
             returns the number of query results.
-nocomplain  silently returns null if the query results in an error.
-list        formats the return value as a list. If not present, the
             return value is joined with \n as required in APL.
-norecursive overrides the default, which assumes all queries are recursive.
-local       performs the query in the iApp's local directory.
-dir         performs the query in a user-specified directory.
-filter      returns the subset of values that match the query spec.

EXAMPLES
set is_edge [expr { ![iapp::get_items -exists -norecursive \
    ltm persistence cookie /Common/cookie] }]

iapp::destination - format ip address and port as a destination or mask

SYNOPSIS
iapp::destination [OPTIONS] ADDR [PORT]

OPTIONS
-mask         returns a mask instead of a destination
-length       specifies the mask using CIDR format (assumes -mask)
-route_domain appends a route domain (incompatible with -mask)

iapp::pool_members - converts APL table into TMSH format

SYNOPSIS
iapp::pool_members [OPTIONS] MEMBER_TABLE

OPTIONS
-port         overrides the port numbers specified in the member table
-route_domain appends a route domain to each address
-aaa_domain   returns a configuration in aaa domain format
-aaa_pool     returns a configuration in aaa pool format
-fields       identifies the column values in the member table
              the default field mapping is:

              TMSH Parameter    Member Table Column
                address           addr
                port              port
                port-secure       port_secure
                connection-limit  connection_limit
                priority-group    priority
                ratio             ratio

iapp::debug - log a message (obscures most passwords)

SYNOPSIS
iapp::debug ARGS

OPTIONS
Any word found in the global list $::SENSITIVES will be obscured. By default, the list contains “password”, “passwd”, “secret”, “account-password”, and “admin-encrypted-password”. The template programmer may add additional words as needed.

iapp::apm_config - alternative APM configuration tool

SYNOPSIS
iapp::apm_config ARRAY_NAME

OPTIONS
none
DESCRIPTION
The apm_config proc provides a tmsh pre-processor for APM configuration, which in most cases will drastically compress the implementation code. To configure APM with this proc, pass it an array of object names and associated meta-tag substitutions. Each object must be categorized as a profile, a resource, or a policy-item. APM agents and customization-groups are derived from these 3 categories as needed. The programmer should verify the procedure’s output by viewing the APM configuration in the APM Visual Editor.
apm_config’s return value is a list of the APM profiles defined in the argument and instantiated by the proc. This allows the procedure call to be embedded directly into a virtual server definition.
These universal meta-tags may be placed anywhere in the array:
<ITEM> The object name, eg. apm_access
<PREFIX> The app name, including folder, eg. /Common/my_app.app/my_app

Profile objects require the following meta-tags:
<PROFILE_TYPE> The tmsh object type, eg. "apm profile access"
<PROFILE_DEF>  The body of the object, eg.:
    access-policy <PREFIX>_apm
     defaults-from /Common/access
     eps-group <PREFIX>_apm_access_eps
     errormap-group <PREFIX>_apm_access_errormap
     general-ui-group <PREFIX>_apm_access_general_ui

apm_config will automatically create default customization-groups for the “-group” lines specified in access profile definitions. In the above example, there is no need to additionally specify a customization-group for errormap and general-ui.
<PROFILE_TYPE> is a catch-all for other APM types, eg:
     apm_sso {
         <PROFILE_TYPE> {apm sso kerberos}
         <PROFILE_DEF>  "account-name <USER>
                         account-password <PASS>
                         realm <REALM>" }

In the example above, <PROFILE_TYPE> and <PROFILE_DEF> are
apm_config meta-tags, while <USER>, <PASS>, and <REALM> must
be substituted before calling apm_config, eg. if these tags are
defined in $pre_proc_map, they may be substituted with:
array set apm_map [string map [subst $pre_proc_map] [array get apm_map]

Resource objects require the following meta-tags:
<RESOURCE_TYPE> The apm resource object type, eg. "webtop"
<RESOURCE_DEF>  The body of the object, eg.:
    "customization-group <ITEM>
     minimize-to-tray false
     webtop-type full"

In the above example, a customization-group is specified. Any
customization-group is assumed to be blank unless further defined by the
<GROUP_DEF> meta-tag, eg. <GROUP_DEF> {type webtop}

Policy-item objects are defined by the following meta-tags:
<AGENT_TYPE>     default "resource-assign"
<AGENT_DEF>      default "customization-group <ITEM>"
<ITEM_AGENT>     default "agents { <ITEM>_ag { type <AGENT_TYPE> }}"
<ITEM_CAPTION>   default "<ITEM>"
<ITEM_COLOR>     default "1"
<ITEM_TYPE>      default "action"
<ITEM_RULES>     defaults to a set of expressions/next-items where specified
<RULE_CAPTION_0> default "fallback"
<RULE_CAPTION_1> default "Successful"
<RULE_CAPTION_2> default "successful"

apm_config generates the APM agent and customization-group definitions
as required for each policy-item, but specific objects may be defined
by using the <AGENT_DEF> and <GROUP_DEF> meta-tags.
To suppress the formation of an APM agent, specify <ITEM_AGENT> {}.

iapp::upgrade_template - template conversion utility

SYNOPSIS
iapp::upgrade_template upgrade_var upgrade_trans

OPTIONS
none
DESCRIPTION
iapp::upgrade_template is a utility used to map APL variables and tables from one template to another. The concept was introduced in TMOS v11.4, when many F5-supplied templates were drastically redesigned. When a user upgrades to v11.4 from a prior version, these template present the older, familiar template view and offer the user an option to upgrade. If the user elects to upgrade, this utility is used to map the user’s configuration data into the APL variables and tables associated with the new template view.
The proc accepts 2 arrays as arguments. The first array pairs the original variable and table names to a Tcl code block that loads the new variable and table names into a conversion array (vx and tx). For example, suppose the original template has an APL variable “monitor_recv” in section “server_pools”, and its value should be transferred to a variable “response” in section “monitor” in the new template. The key-value pair in the array would look like this:
::server_pools__monitor_recv {
    [set vx(monitor__response) $::server_pools__monitor_recv]
}
Since the new variable is almost always set to the old variable’s value, the abbreviation “##” may be substituted to represent the old value:
::server_pools__monitor_recv {
    [set vx(monitor__response) ##]
}
The proc’s second argument is an array that defines the necessary value translations from the old to the new template. For example, the programmer may wish to universally translate an old template value of “Yes” to a new template value of “yes”. Within this array, the proc also accepts translations that are specific to one variable. For example, the programmer may wish to translate “Yes” to “/Common/ntlm”, but only for the variable $server__ntlm. The array in this example would look like this:
array set upgrade_trans_arr {
     Yes yes
     server__ntlm { Yes /Common/ntlm }
 }

iapp::downgrade_template - template undo conversion utility

SYNOPSIS
iapp::downgrade_template pivot_var upgrade_var downgrade_table

OPTIONS
none
DESCRIPTION
iapp::downgrade is essentially a procedure to “undo” the effect of iapp::upgrade. Since BIG-IP retains APL variables indefinitely, there is no need to perform a reverse translation. However, BIG-IP does not retain APL tables. The downgrade_table argument provides a list of tables that must be repopulated in order to bring the user back to square one.
The other two arguments, pivot_var and upgrade_var, identify the APL variables that record the upgrade state and original value of the upgrade state variable. This is the most confusing part of the upgrade process, but in essence, its purpose is simply to determine which state the template is currently in. There are 4 possible states for an upgradeable template:
1. Old template view for an existing iApp, showing the option to upgrade.
2. New template view for an upgraded iApp, showing the option to downgrade.
3. New template view for a new iApp, not showing the downgrade option.
(iApps built new in v11.4 are not allowed to convert to the v11.3 view)
The v11.4 f5.http template contains a full upgrade from v11.3 using this utility, and may be used as further reference.