CLI script include: f5.app_utils

Introduction

The app_utils cli script contains a set of procedures that are used by the built-in iApp templates. These procedures are a set of shared helper functions that are used by the various F5 supported iApp Templates. They are not presented as a complete API, but they are available for anyone’s use in other iApp Templates.
An iApp template that wants to include this set of procs needs to define some constants that some of these procs require to opperate.
set NO_ANSWER “No”
set YES_ANSWER “Yes”
set WAN_OPTION “WAN”
set EMPTY_STRING “EMPTY_STRING_NO_VALUE_PRESENT”
set ADDR_FIELD “addr”
set PORT_FIELD “port”
set RATIO_FIELD “ratio”
set CONNECTION_LIMIT_FIELD “connection_limit”
set HOST_FIELD “host”
set ONE_SPACE ” “
set HTTP_11_VERSION_STRING “”Version 1.1””

Procedures


Table of Contents[Hide/Show]


`get_items_local_only_not_recursive: <#get_items_local_only_n
ot_recursive:_5>`__
equal_or_later:_18>`__
`get_bigip_version_is_equal_or_earlier: <#get_bigip_version_i
s_equal_or_earlier:_19>`__
`get_bigip_version_is_equal: <#get_bigip_version_is_equal:_20
>`__
`get_compression_content_type_includes: <#get_compression_con
tent_type_includes:_25>`__
`add_compression_content_type_includes: <#add_compression_con
tent_type_includes:_26>`__
`get_compress_parent_profle: <#get_compress_parent_profle:_28
>`__
get_caching_parent_profle: <#get_caching_parent_profle:_29>
ofiles:_31>`__
`create_one_connect_and_ntlm_profiles: <#create_one_connect_a
nd_ntlm_profiles:_32>`__
create_server_ssl_profile: <#create_server_ssl_profile:_34>
_profile_with_key_cert:_35>`__
`create_https_redirect_irule: <#create_https_redirect_irule:_
36>`__
`create_https_redirect_irule_specific_ports: <#create_https_r
edirect_irule_specific_ports:_37>`__
ride:_46>`__
`do_tcp_request_queue_settings: <#do_tcp_request_queue_settin
gs:_47>`__

get_items:


Description
Gets a list of items of the type specified by args that exist on the BIG-IP.
The search is performed with the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
For example: To return the list of pools.
get_items /ltm pool

Parameters
  • args - The component path of the desired object type

Return Value: The sorted list of items


get_items_local_only:


Description
Gets a list of items of the type specified by args that exist on the BIG-IP in the local folder only.
The search is performed with the recursive keyword.
For example: To return the list of pools.
get_items_local_only /ltm pool

Parameters
  • args - The component path of the desired object type

Return Value: The sorted list of items


get_items_not_recursive:


Description
Gets a list of items of the type specified by args that exist on the BIG-IP, but without trying to look in subfolders.
The search is performed without the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
For example: To return the list of pools.
get_items_not_recursive /ltm pool

Parameters
  • args - The component path of the desired object type

Return Value: The sorted list of items


get_items_local_only_not_recursive:


Description
Gets a list of items of the type specified by args that exist on the BIG-IP, but in the local folder only and no subfolders.
The search is performed without the recursive keyword.
For example: To return the list of pools.
get_items_local_only_not_recursive /ltm pool

Parameters
  • args - The component path of the desired object type

Return Value: The sorted list of items


get_items_filter:


Description
Gets a filtered list of items of the type specified by args that exist on the BIG-IP. The list is filtered to only contain items with a particular field set to a particular field value.
The search is performed with the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
For example: To return the list of pools with a load balancing method of least-connections-members .
get_items_filter load-balancing-mode least-connections-members /ltm pool

Parameters
  • field_name - The name of the field to filter on

  • field - The value that is expected in the field.

  • args - The component path of the desired object type

Return Value: The sorted list of filtered items


get_items_prefix:


Description
Gets a list of items whose names have a particular prefix of the type specified by args that exist on the BIG-IP.
The search is performed with the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
For example: To return the list of pools with names starting with name_prefix_
get_items_prefix name_prefix_ /ltm pool

Parameters
  • prefix - The name prefix to filter on

  • args - The component path of the desired object type

Return Value: the sorted list of results.


get_vlans:


Description
Gets a list of VLANs that exist on the BIG-IP.
The search is performed with the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
Parameters None
Return Value: The sorted list of VLANs


sort_results:


Description
Sort the list of results alphabetically. Items in the list are separated by a space.
Parameters
  • results - the list of results to sort

Return Value: a sorted version of the results list, separated by \n


sort_results_with_spaces:


Description
Sort the list of results alphabetically. Items in the list are separated by a \n.
Parameters
  • results - the list of results to sort

Return Value: a sorted version of the results list, separated by \n


sort_wa_policy_results:


Description
Deprecated. Legacy.
Sort the list alphabetically. Items are separated with a \n.
Parameters
  • results - The list to sort

Return Value: The sorted results list


get_custom_wa_policies:


Description
Get the list of custom WAM policies on the BIG-IP. Leave out any built-in WAM policies.
Parameters None
Return Value: The sorted list of custom WAM policies


get_provisioned:


Description
Determine if a particular module is currently provisioned on the BIG-IP.
Parameters
  • module - The module to test

Return Value: Returns “provisioned” is the module in question is provisioned, and “not_provisioned” otherwise.


get_platform:


Description
Determine the hardware platform.
Parameters None
Return Value: The hardware platform


get_is_viprion:


Description
Determines if this BIG-IP is a Viprion.
Parameters None
Return Value: Returns true if the BIG-IP is a viprion, false otherwise


get_ltm_monitors_filter:


Description
Get a list of the monitors of the type(s) specified that exist on the BIG-IP.
The search is performed with the recursive keyword. The search is done in the local folder and also in /Common if the local folder is different from /Common.
For example: To return the list of tcp, http, and https monitors.
get_ltm_monitors_filter tcp http https

Parameters
  • monitor_types - the type or list of types of monitors to include

Return Value: A sorted list of monitors that exist on the BIG-IP


get_bigip_version:


Description
returns the version number that the BIG-IP is currently running
Parameters None
Return Value: The version that the BIG-IP is currently running


get_bigip_version_is_equal_or_later:


Description
Determines is the BIG-IP version string is equal to or greater than the supplied version string that is supplied.
Parameters
  • compare_version - the version to compare against

Return Value: True if the actual version of the BIG-IP is equal or greater than the supplied version string, false otherwise.


get_bigip_version_is_equal_or_earlier:


Description
Determines is the BIG-IP version string is equal to or less than the supplied version string that is supplied.
Parameters
  • compare_version - the version to compare against

Return Value: True if the actual version of the BIG-IP is equal or less than the supplied version string, false otherwise.


get_bigip_version_is_equal:


Description
Determines is the BIG-IP version string is equal to the version string that is supplied.
Parameters
  • compare_version - the version to compare against

Return Value: True if the actual version of the BIG-IP is equal to the supplied version string, false otherwise.


get_ssl_keys:


Description
Return a dynamically generated list of the SSL keys available on the BIG-IP
Parameters None
Return Value: A list of the SSL keys available on the BIG-IP


get_ssl_certs:


Description
Return a dynamically generated list of the SSL certs available on the BIG-IP
Parameters None
Return Value: A list of the SSL certs available on the BIG-IP


do_tmsh_create:


Description
Perform a tmsh::create command, logging the command to scriptd.out and also logging any errors that occur to scriptd.out
Parameters
  • component - The object type, such as “ltm pool”

  • arguments - The rest of the create command string, the object name followed by any parameters to set.

Return Value: None


do_tmsh_modify:


Description
Perform a tmsh::modify command, logging the command to scriptd.out and also logging any errors that occur to scriptd.out
Parameters
  • component - The object type, such as “ltm pool”

  • arguments - The rest of the modify command string, the object name followed by any parameters to set.

Return Value: None


get_compression_content_type_includes:


Description
Returns the standard list of compression content type includes that PME uses, encapsulated in \{ amd \}
\{ &ltthe list> \}

Parameters None
Return Value: The list of content type includes


add_compression_content_type_includes:


Description
Adds the standard list of compression content type includes that PME uses to the compression profile.
Parameters
  • profile_name - the compression profile to modify

Return Value: None


get_http_parent_profile:


Description
This actually just returns the one http profile name right now, http.
Parameters None
Return Value: always returns ‘http’


get_compress_parent_profle:


Description
This actually just returns the one compression profile name right now. wan-optimized-compression.
Parameters None
Return Value: always returns wan-optimized-compression


get_caching_parent_profle:


Description
Returns the name of the correct parent profile to use when creating the caching profile, based on if WAM is being deployed or not.
Parameters
  • do_configure_wa - this should be set to the YES_ANSWER constant if WAM is being used in this deployment, and NO_ANSWER otherwise.

Return Value: The name of the parent profile to use.


is_lb_method_ratio:


Description
Determines if this load balancing method is a ratio method.
Parameters
  • lb_method - the load balancing method in question

Return Value: 1 if the LB method is a ration method, 0 otherwise.


create_http_comp_accel_profiles:


Description
Create an HTTP profile and, possibly, a compression and/or caching profile. Return the list of profile names.
Parameters
  • name_prefix - The name prefix to use for the object creation

  • clients_connect_on_lan_or_wan - Do clients connect over a LAN or a WAN? If this value is set to the constant WAN_OPTION, then the proc creates a compression profile, otherwise it does not.

  • use_cache - if this is set to the constant YES_ANSWER, then create a caching profile that inherits from the optimized-caching parent profile.

  • do_configure_wa - if this is set to the constant YES_ANSWER, then create a caching profile that inherits from the optimized-acceleration parent profile. The application specified in the parameter wa_app_name is attached to the caching profile.

  • wa_app_name - If do_configure_wa is set to the constant YES_ANSWER then this WAM application name is attached to the caching profile.

  • ssl_rewrite - This parameter affects the redirect-rewrite attribute of the http profile. If SSL offloading is in effect, then set this parameter to the YES_ANSWER constant, and redirect-rewrite will be set to matching. Set this parameter to ‘all’ to set redirect-rewrite to all. Other values set redirect-rewrite to none.

Return Value: The list of profiles that were created.


create_one_connect_and_ntlm_profiles:


Description
Create a OneConnect profile, and an NTLM profile to go with it, if it is required.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • create_ntlm_profile - If the back-end servers use NTLM authentication then set this parameter to the YES_ANSWER constant and a ntlm profile will be created.

  • using_snat - If the virtual server will be using SNAT, then the one-connect needs to have its source-mask set to 255.255.255.255. Set this parameter to the YES_ANSWER constant to make this happen. A source mask of 0.0.0.0 will be set otherwise.

Return Value: A string containing either just the OneConnect or both the OneConnect and the NTLM profile, if one was created.


create_ssl_profile:


Description
Create a client SSL profile using the supplied SSL key and cert.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • key - The SSL key to use in creating the profile

  • cert - The SSL cert to use in creating the profile

Return Value: The name of the SSL profile that was created


create_server_ssl_profile:


Description
Create a server SSL profile with no key/cert attached. This is the most common form of the server-side SSL profile.
Parameters
  • name_prefix - The name prefix to use fot the object creation

Return Value: The name of the SSL profile that was created


create_server_ssl_profile_with_key_cert:


Description
Create a server SSL profile. The SSL key and cert are optional, and not required in most cases. Set these parameters to the EMPTY_STRING constant to create a profile that doesn’t use a key and cert.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • key - The SSL key to use in creating the profile - may be set to the EMPTY_STRING constant

  • cert - The SSL cert to use in creating the profile - may be set to the EMPTY_STRING constant

Return Value: The name of the SSL profile that was created


create_https_redirect_irule:


Description
Deprecated. Legacy.
This just calls the create_https_redirect_irule_specific_ports descrtibed below.
Parameters
  • name_prefix - The name prefix to use fot the object creation

Return Value: The name of the iRule that was created.


create_https_redirect_irule_specific_ports:


Description
Create an iRule that will redirect traffic from an HTTP virtual server to an HTTPS virtual server, specifying the ports for those virtual servers. In the most common case, where the HTTP port is 80 and the HTTPS port is 443, then just return the name of the built-in redirect iRule.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • original_port - the port number of the http VS that will attach the iRule

  • new_port - the port number to redirect traffic to

Return Value: The name of the iRule that was created.


create_wa_app:


Description
Create a WAM application object
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • wa_policy_name - The WAM policy for the WAM application to use.

  • wa_description - A description for this WAM application

  • hosts - A list of hosts that the WAM application should respond to. This list should be the list produced by a table APL element with a single string element input. For this proc to work, you must set the constant HOST_FIELD to the name of that single input in the table.

Return Value: The name of the WAM application that was created


create_wa_app_new:


Description
Create a WAM application object. This is just like the create_wa_app proc above, except that it allows you to set the X WA Info header and perf-monitor attributes.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • wa_policy_name - The WAM policy for the WAM application to use.

  • wa_description - A description for this WAM application

  • hosts - A list of hosts that the WAM application should respond to. This list should be the list produced by a table APL element with a single string element input. For this proc to work, you must set the constantHOST_FIELD to the name of that single input in the table.

  • x_wa_info_header - The header to use. Possible values are none”, “standard”, and “debug”.

  • perf_monitor - The perf-monitor setting. Possible values are “enabled”, and “disabled”.

  • data_retention_period - The data retention period for the per-monitor. If perf_monitor is set to “enabled” then this value is used.

Return Value: The name of the WAM application that was created


is_safe_app_name:


Description
Validates that the app name is legal for use as an object name prefix.
Parameters
  • app_name - the app name to evaluate.

Return Value: true is the app name is considered safe, false otherwise.


create_http_class:


Description
Creates an HTTPClass profile. It is assumed that the desire is to enable ASM. Enabling WAM is an option, but this use is deprecated.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • asm_predefined_policy_name - The predefined policy name to use.

  • asm_language_choice - the language choice for the ASM policy

  • wa_enabled - If this is set to the constant YES_ANSWER, then WAM is enabled on the HTTPClass. This use is deprecated. This value should be set to No.

Return Value: The name of the HTTP Class that was created.


create_monitor:


Description
Creates an HTTP or HTTPS type monitor. This procedure is not appropriate for other monitor types.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • monitor_type - The type of monitor to create. Legal values are “http” and “https”

  • monitor_interval - How often, in seconds, the monitor should run. The timeout value will be set to 3X + 1 of this value.

  • monitor_send - The send string for the monitor to send

  • monitor_recv - The recv string that the monitor expects back.

  • http_version - Do the back-end servers expect traffic in HTTP 1.0 or 1.1 format? Legal values are “Version 1.0” and “Version 1.1”

  • dns_name - The DNS name to send in the query, if this is http version 1.1

Return Value: The name of the monitor that was created.


is_ipv6:


Description determines if the given IP address is in IPv6 format or not. This works regardless of is the address contains the port number. This procedure does not evaluate is the address is of a legal format, it just dtermines if its IPv6 vs. IPv4, assuming that they are legal addresses.
Parameters
  • addr - The IP address to evaluate

Return Value: Returns Yes if this is an IPv6 address, No if this is an IPv4 address.


create_destination:


Description
Combines the supplied IP address and port together with the proper connector to create a destination.
If the IP address is in IPv4 format, then the destination is created using a colon, like this &ltIP Address>:&ltport>
If the IP address is in IPv6 format, then the destination is created using a period, like this &ltIP_Address>.&ltport>
Parameters
  • addr - the IP address

  • port - the port

Return Value: the destination string


create_pool:


Description
Creates an LTM pool
Parameters
  • name_prefix - The name prefix to use for the object creation

  • monitor_name - The name of the monitor to attach to the pool. To not use a monitor, set this to ‘none’.

  • servers - The list of servers to fill the pool with. This list should
    be a list that comes from a table APL element containing address,
    port, and optional connection limit and ratio fields. The names of
    those fields should be stored in the constants ADDR_FIELD,
    PORT_FIELD, CONNECTION_LIMIT_FIELD, and RATIO_FIELD. Below is an
    example of the form this table should take.
    table servers {
    string addr required validator "IpAddress"
    string port default "7001" required validator "PortNumber" display "small"
    string connection_limit default "0" required validator "NonNegativeNumber" display "small"
    optional ( lb_method_choice == "ratio-member" ||
    lb_method_choice == "ratio-node" ||
    lb_method_choice == "ratio-session" ||
    lb_method_choice == "ratio-least-connections-member" ||
    lb_method_choice == "ratio-least-connections-node" ||
    lb_method_choice == "dynamic-ratio-member" ||
    lb_method_choice == "dynamic-ratio-node" ) {
    string ratio default "1" validator "NonNegativeNumber" display "small"
    }
    }
    


  • lb_method - The load balancing method to use

Return Value: The name of the pool that was created.


create_pool_with_port_override:


Description
Creates an LTM pool. This is exactly the same as the create_pool proc defined above, except that the pool field of the table is ignored, if it exists at all. Instead, the supplied port number is substituted in its place.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • monitor_name - The name of the monitor to attach to the pool. To not use a monitor, set this to ‘none’.

  • servers - The list of servers to fill the pool with. This list should
    be a list that comes from a table APL element containing an address
    and optional connection limit and ratio fields. The names of
    those fields should be stored in the constants ADDR_FIELD,
    CONNECTION_LIMIT_FIELD, and RATIO_FIELD. Below is an example of the
    form this table should take.
    table servers {
    string addr required validator "IpAddress"
    string port default "7001" required validator "PortNumber" display "small"
    string connection_limit default "0" required validator "NonNegativeNumber" display "small"
    optional ( lb_method_choice == "ratio-member" ||
    lb_method_choice == "ratio-node" ||
    lb_method_choice == "ratio-session" ||
    lb_method_choice == "ratio-least-connections-member" ||
    lb_method_choice == "ratio-least-connections-node" ||
    lb_method_choice == "dynamic-ratio-member" ||
    lb_method_choice == "dynamic-ratio-node" ) {
    string ratio default "1" validator "NonNegativeNumber" display "small"
    }
    }
    


  • lb_method - The load balancing method to use

  • port_number - The port number to use in place of whatever was speficied in the table.

Return Value: The name of the pool that was created.


do_tcp_request_queue_settings:


Description
Attach TCP request queueing settings to a pool
Parameters
  • pool_name - The name of the pool to modify

  • do_request_queuing - Turn on request queueing? Legal values are the constant YES_ANSWER to enable tcp request queueing and NO_ANSWER to disable it.

  • queue_depth - How long should the queue be? Specify the number of TCP requests that can be queued at any one time.

  • timeout - The length of time a TCP request can remain the queue before it times out. Specify the time in seconds.

Return Value: None


get_file_contents:


Description
Open the file specified by the parameter filename and return its contents as blob of text.
Parameters
  • filename - the name of the file to retreive.

Return Value: The file’s contents. In the case of an error opening the file, the contents will be an empty string.


create_http_vs:


Description
Creates an HTTP virtual server. This proc just append the string “_http” to the name_prefix and calls create_vs.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • destination - The destination address and port for the virtual server. This should be specified as &ltaddr>:&ltport> for IPv4 and as &ltaddr&gt.&ltport> for IPv6.

  • snat - What kind of SNAT behavior should this virtual server have? Legal values are “none” for no SNAT, “automap” for SNAT automap, or the name of a snat pool if one of those is desired.

  • pool_name - The name of the pool to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • profile_names - A list of profiles to attach to the virtual server

  • persist_profile - the persist profile to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • tcp_server_profile_name - The serverside TCP profile

  • tcp_client_profile_name - The clientside TCP profile. To use the same profile for both sides, make these two parameters equal.

Return Value: The name of the virtual server that is created.


create_https_vs:


Description
Creates an HTTPS virtual server. This proc just append the string “_https” to the name_prefix and calls create_vs.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • destination - The destination address and port for the virtual server. This should be specified as &ltaddr>:&ltport> for IPv4 and as &ltaddr&gt.&ltport> for IPv6.

  • snat - What kind of SNAT behavior should this virtual server have? Legal values are “none” for no SNAT, “automap” for SNAT automap, or the name of a snat pool if one of those is desired.

  • pool_name - The name of the pool to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • profile_names - A list of profiles to attach to the virtual server

  • persist_profile - the persist profile to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • tcp_server_profile_name - The serverside TCP profile

  • tcp_client_profile_name - The clientside TCP profile. To use the same profile for both sides, make these two parameters equal.

Return Value: The name of the virtual server that is created.


create_vs:


Description
Creates an HTTP/HTTPS virtual server.
Parameters
  • name_prefix - The name prefix to use fot the object creation

  • destination - The destination address and port for the virtual server. This should be specified as &ltaddr>:&ltport> for IPv4 and as &ltaddr&gt.&ltport> for IPv6.

  • snat - What kind of SNAT behavior should this virtual server have? Legal values are “none” for no SNAT, “automap” for SNAT automap, or the name of a snat pool if one of those is desired.

  • pool_name - The name of the pool to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • profile_names - A list of profiles to attach to the virtual server

  • persist_profile - the persist profile to attach to the virtual server. Set this to the constant EMPTY_STRING to use no pool.

  • tcp_server_profile_name - The serverside TCP profile

  • tcp_client_profile_name - The clientside TCP profile. To use the same profile for both sides, make these two parameters equal.

Return Value: The name of the virtual server that is created.

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.