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.
The BIG-IP API Reference documentation contains community-contributed content. F5 does not monitor or control community code contributions. We make no guarantees or warranties regarding the available code, and it may contain errors, defects, bugs, inaccuracies, or security vulnerabilities. Your access to and use of any code available in the BIG-IP API reference guides is solely at your own risk.