MyF5 Sign In

Operations Guide

K59714939: External APIs | BIG-IP TMOS operations guide

Published Date: Oct 9, 2018 Updated Date: Feb 16, 2023

Applies to:

Chapter 16: External APIs

Table of contents | << Previous chapter | Next chapter >>

Contents
Chapter sections

At a glance–Recommendations
Background
BIG-IP APIs and automation interfaces
tmsh
iControl
iApps
iCall
iRules
SNMP
F5 Automation Tool Chain
Procedures
Recommended practices
tmsh authentication and authorization configuration
iControl authentication and authorization configuration
iApps authentication and authorization configuration
iCall authentication and authorization configuration
SNMP authentication and authorization configuration

At a glance–Recommendations
F5 has not identified any recommendations for this section.

Background
This section provides context for our recommended procedures in the form of overviews and supplemental information.

BIG-IP APIs and automation interfaces

The BIG-IP system has a number of external APIs and interfaces, which are useful for a wide range of administrative functions,
including configuration, monitoring, and reporting. These APIs and interfaces do not need to be maintained.

The BIG-IP system contains or uses the following APIs and programming or automation interfaces:

TMOS Shell (tmsh)

iControl
iControl SOAP
iControl REST
iControl LX
iApps
iApps LX
iCall
iRules
iRules LX
SNMP
F5 Automation Tool Chain

tmsh

tmsh is the BIG-IP command-line interface (CLI). It shares many of the same properties and features of other networking and
systems industry shells, such as Advanced Shell (bash), Cisco IOS, and Juniper JunOS. tmsh uses a Tool Command Language (Tcl)
syntax and command-set, which has been expanded and extended by F5 for tmsh.

BIG-IP single configuration file (SCF) and on-disk configuration files are all written in native tmsh syntax and have advanced
scripting capabilities, all based on F5 enhancements to Tcl.
tmsh is the basis for other interfaces, such as iApps and iCall, and is the base mapping for iControl REST.
tmsh can be used to automate any tmsh commands.
For more information:

tmsh help /cli script

tmsh contains a built-in help system.

Files related to tmsh

/config/bigip_script.conf — Stores tmsh scripts added to the system

/config/bigip_user.conf — User configuration, including shell preference
/config/bigip_base.conf — Base-level network and system configuration, such as VLANs, self IPs, device service clustering
(DSC), and provisioning
/config/bigip.conf — High-level traffic management and system configuration, such as virtual servers, profiles, access policies,
iRules, and authentication settings

Logs related to tmsh

/var/log/ltm — Default location for most core BIG-IP messages

/var/log/audit.log — Audit logging, if auditing is enabled

iControl

iControl is the open, web services-based API used by the BIG-IP system that allows complete, dynamic, programmatic control of F5
configuration objects. It enables applications to work in concert with the underlying network based on true software integration.

iControl comes in two forms, iControl SOAP and its successor iControl REST. While both forms are supported, iControl SOAP is no
longer being fully developed and is in the process of being deprecated. New implementations should use iControl REST.
iControl SOAP is based on Simple Object Access Protocol (SOAP), a legacy protocol which was once very popular for web-based
APIs. iControl SOAP was released in BIG-IP 9.0. It is more difficult to program in than iControl REST, but external libraries are
available to assist in writing code.

iControl REST uses modern web standards in the form of Representational State Transfer (REST) and JavaScript Object Notation
(JSON). iControl REST is used in BIG-IP systems 11.4 and later. Its API is based on tmsh, sharing the same overall layout and
structure. It is essentially a JSON version of tmsh that adheres to REST standards. iControl REST complies with modern web-based
programming paradigms and is easier to use and implement than iControl SOAP.

iControl LX allows you to extend iControl functionality with a custom REST API endpoint. iControl LX runs on a node.js daemon
called restnoded, so you must create the extension using the JavaScript programming language. For more information, refer to
iApps LX/iControl LX Documentation.

iControl automation is generally written using systems and languages external to the BIG-IP system. It is your responsibility to
ensure they are properly versioned and backed up.

Logs related to iControl

/var/log/ltm — Default location for most core BIG-IP messages

/var/log/audit.log — Audit logging, if auditing is enabled

iApps

iApps is the BIG-IP system framework for deploying services-based, template-driven configurations on BIG-IP systems running BIG-
IP 11.0.0 and later. iApps allows creation of application-centric deployment interfaces on BIG-IP systems, reducing configuration
time and increasing accuracy of complex traffic management implementations. The goal of iApps is to enable Subject-Matter
Experts (SME) to build finely tuned configurations that can be deployed by administrators who possess application-level expertise
without requiring them to be concerned about lower-level networking details.

The iApps is primarily used to package and deliver expert-created configurations to a non-expert audience. Its implementation
language is standard tmsh scripting with environmental variables for Application Presentation Language (APL) user selections. It
uses the F5-specific APL to render a user-facing presentation interface. It allows prescriptive abstraction of repeatable
configurations based on user-facing input.

Configuration information is stored in UCS and SCF backups by default, with no special action required. For more information, refer
to Backup and Data Recovery.

iApps LX is built on the iControl LX framework and allows you to create iApps with any externally managed device that accepts API
requests, such as an OpenStack interface, LDAP server, or cloud connector. Since the feature relies on the iControl LX framework,
which runs on a node.js daemon called restnoded, you must create iApps LX Application Services using the JavaScript
programming language. For more information, refer to iApps LX/iControl LX Documentation.

Files related to iApps

/config/bigip_script.conf — Stores iApp Templates added to the system.

Logs related to iApps

/var/tmp/script.log — All non-APL output from iApp Templates goes to this file.

iCall

iCall is an event-based automation system for the BIG-IP control plane, introduced in BIG-IP 11.4. It can send and receive external
events using any ports or protocols and can be useful for integration into upstream orchestration, or for driving orchestration
directly from the BIG-IP system.

It uses standard tmsh syntax and is still in the early phases of development, so there is minimal documentation. All events are user-
defined and none of the internal events are currently exposed.
Configuration information is stored in UCS and SCF backups by default, with no special action required. For more information, refer
to Backup and Data Recovery.

Files related to iCall

/config/bigip_script.conf — Stores all iCall configuration and scripts added to the system.

Logs related to iCall

/var/tmp/script.log — All output from iCall scripts goes to this file.

iRules

iRules is a powerful and flexible feature within BIG-IP Local Traffic Manager (LTM) that you can use to manage your network traffic.
Using syntax based on the industry-standard Tools Command Language (Tcl), greatly enhanced by F5, iRules not only allows you to
select pools based on header data, but also allows you to direct traffic by searching on any type of content data that you define.
Thus, the iRules feature significantly enhances your ability to customize your content switching to suit your exact needs.

iRules fully exposes BIG-IP internal Traffic Management Microkernel (TMM) packet/data processing, allowing inspection,
manipulation and optimization and contains a number of mechanisms for exporting information out of the data-plane.

Out-of-band/side-band connections: Enable asynchronous communication with outside hosts from within TMM/iRules. (For more
information, refer to iRules Sideband documentation on DevCentral.

iRules LX is a way to extend iRules to use the capabilities of node.js. You can use iRules LX by way of RPC where you can send a
portion of code to node.js to run and return the results. You can also use it by way of the streaming interface where you employ an
ILX profile. You must create iRule LX scripts with the JavaScript programming language. For more about iRules LX, refer to
iRulesLX Home.

Important iRules terms

iFiles: Stores data/content files and external class-lists for use by iRules.
iStats: iRules variables that are accessible in tmsh and the other control-plane languages (iApps, iCall, and so on.). It is the
primary vehicle for information sharing between control-plane and data-plane.

iRules management

Configuration information is stored in UCS and SCF backups by default, with no special action required. For more information, refer
to Backup and Data Recovery.

Files related to iRules

/config/bigip.conf — Stores all iRules added to the system.

Logs related to iRules

/var/log/ltm — All logging output from iRules goes to this file.

SNMP

SNMP is an industry-standard application-layer protocol, most commonly used by centralized monitoring and automation systems.
It is a part of the TCP/IP protocol suite.

SNMP Management

Configuration information is stored in UCS and SCF backups by default, with no special action required. For more information, refer
to Backup and Data Recovery.

The supported method for modifying the SNMP configuration is using tmsh. Editing the SNMP configuration files directly is not
supported and likely results in loss of configuration changes.
Files related to SNMP

/config/bigip_base.conf — Stores SNMP configuration, as configured using tmsh.

Logs related to SNMP

/var/log/snmpd.log — All logging output from SNMP goes to this file.

F5 Automation Tool Chain

The F5 Automation Tool Chain is a suite of software that enables you to programmatically configure BIG-IP systems using
infrastructure as code (IaC). It is comprised of the following:

iControl LX extensions that provide a declarative API:

Application Services 3 Extension (AS3)  - For configuring layer 4-7 BIG-IP application services (virtual servers, pools, nodes,
etc.).
Declarative Onboarding Extension (DO) - For configuring layer 1-3 BIG-IP configuration (VLANs, self-IPs, routes, etc.).
F5 Telemetry Streaming (TS) - For configuring the BIG-IP system to send statistics and events to external analytics
consumers.
Templatized AS3 declarations:
F5 Application Services Templates (FAST) - A templating system that replaces iApp templates. FAST uses AS3 declarations
to deploy application services.

For more information, refer to Cloud Docs Home page.

Procedures
There are no specific procedures required for maintaining the operational efficiency of these interfaces. However, there are some
recommended practices to keep in mind when implementing them.

Recommended practices

The BIG-IP system APIs and interfaces are powerful tools and must be created and maintained with the same care as any other
software development project. Inconsistent naming conventions, missing code comments, and unreviewed code combined with
weak change management are the source of many upgrade and maintenance issues.

Coding best practices with BIG-IP APIs

Use port lockdown to limit access to necessary interfaces and ports.

Always develop and test in a non-production environment (BIG-IP VE, for example).
Use consistent syntax and style.
Be sure to comment effectively and implement revision control.
Audit all BIG-IQ system automation and scripting prior to upgrade to determine ongoing support for the APIs and interfaces
employed.

For more information, refer to Appendix B: Deployment and Response Methodologies.

Upgrades

Before upgrading, verify there are no behavior changes when upgrading in a lab or pre-production environment.
After upgrading, confirm operation and functionality of each interface.

For more information, refer to Appendix B: Deployment and Response Methodologies.

Log review

Regularly review logs for alerts or errors.

 Investigate and document all alert and error messages.
Investigate warnings to determine their relevance and any necessary actions.
Use debug logging only during troubleshooting. This is especially true when using iRules, which can influence production
traffic negatively.
Use debug logging for specific investigation. Due to verbose logging, the system can generate high volume of messages.

For more information, refer to Log Files and Alerts.

tmsh authentication and authorization configuration

Configuration information is stored in UCS and SCF backups by default, with no special action required. For more information, refer
to Backup and Data Recovery.

Configuring tmsh to be a user's default shell at the command line

Enter the following command syntax:

tmsh modify /auth user <username> shell tmsh

Configuring tmsh to be a user's default shell using the Configuration utility

1. Go to System > Users > User List.

2. Select the user name.
3. For Terminal Access, select tmsh.
4. Select Update.

Setting up self IP port lockdown to accept tmsh traffic on port 22

Port lockdown specifies the protocols and services from which a self IP address can accept traffic. It is a security feature that allows
you to specify particular UDP and TCP protocols and services from which the self IP address can accept traffic. By default, a self IP
address accepts traffic from these protocols and services:

For UDP, the allowed protocols and services are: DNS (53), SNMP (161), RIP (520).
For TCP, the allowed protocols and services are: SSH (22), DNS (53), SNMP (161), HTTPS (443), 4353 (iQuery).

You access tmsh remotely using SSH on port 22. Management port 22 is available on the management interface by default. If self
IP addresses are not configured to allow port 22 to receive traffic for tmsh, you need to configure port lockdown settings.

Configuring self IP port lockdown at the command line

Enter the following command syntax:

modify net self <name or ip address> allow-service add { tcp:22 }

Configuring self IP port lockdown using the Configuration utility

1. Go to Network > Self IPs.

2. Select the IP address you want to configure.
3. For Port Lockdown, select the port and protocol that you want to allow.
4. Select Update.

For more information, refer to the Self IP Addresses chapter in the BIG-IP TMOS: Routing Administration guide.

Note: For information about how to locate F5 product manuals, refer to K98133564: Tips for searching AskF5 and finding product
documentation.

iControl authentication and authorization configuration

iControl uses the same user role as tmsh and the BIG-IP Configuration utility.
Assigning iControl administrative rights at the command line

1. Log in to tmsh by entering the following command:

tmsh
2. Enter the following command syntax:

modify auth user <username> role admin

Assigning iControl administrative rights using the Configuration utility

1. Go to System > Users > User List.

2. Select the user name of the user you want to modify.
3. For Partition Access, for Role, select Administrator.
4. Select Update.

Setting up self IP port lockdown to accept iControl traffic on port 443

Port lockdown specifies the protocols and services from which a self IP address can accept traffic. It is a security feature that allows
you to specify particular UDP and TCP protocols and services from which the self IP address can accept traffic. By default, a self IP
address accepts traffic from these protocols and services:

For UDP, the allowed protocols and services are: DNS (53), SNMP (161), RIP (520)
For TCP, the allowed protocols and services are: SSH (22), DNS (53), SNMP (161), HTTPS (443), 4353 (iQuery)

Note: Management port 443 is available on the management interface by default. BIG-IP 11.6.0 and earlier do not support port
filtering on the management port interface.

You access iControl remotely via HTTPS on port 443. If self IP addresses are not configured to allow port 443 to receive traffic for
iControl, you need to configure port lockdown settings.

Configuring self IP port lockdown at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command syntax:

modify net self <name or ip address> allow-service add { tcp:443 }

Configuring self IP port lockdown using the Configuration utility

1. Go to Network > Self IPs.

2. Select the IP address you want to configure.
3. For Port Lockdown, select the port and protocol that you want to allow.
4. Select Finished.

For more information, refer to the Self IP Addresses chapter in the BIG-IP TMOS: Routing Administration guide.

Note: For information about how to locate F5 product manuals, refer to K98133564: Tips for searching AskF5 and finding product
documentation.

iApps authentication and authorization configuration

Assigning iApps administrative rights at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command syntax:

 modify auth user <username> role admin

Assigning iApps administrative rights using the Configuration utility

1. Go to System > Users > User List.

2. Select the user name of the user you want to modify.
3. For Partition Access, for Role, select Administrator.
4. Select Update.

Setting up self IP port lockdown to accept Configuration utility traffic on port 443

Port lockdown specifies the protocols and services from which a self IP address can accept traffic. It is a security feature that allows
you to specify particular UDP and TCP protocols and services from which the self IP address can accept traffic. By default, a self IP
address accepts traffic from these protocols and services:

For UDP, the allowed protocols and services are: DNS (53), SNMP (161), RIP (520).
For TCP, the allowed protocols and services are: SSH (22), DNS (53), SNMP (161), HTTPS (443), 4353 (iQuery).

Note: Management port 443 is available on the management interface by default. BIG-IP 11.6.0 and earlier do not support port
filtering on the management port interface.

You access iApps on the Configuration utility by way of HTTPS on port 443. If self IP addresses are not configured to allow port
443 to receive traffic for iControl, you need to configure port lockdown settings.

Configuring self IP port lockdown at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command syntax:

modify net self <name or ip address> allow-service add { tcp:443 }

Configuring self IP port lockdown using the Configuration utility

1. Go to Network > Self IPs.

2. Select the IP address you want to configure.
3. In Port Lockdown, select the port and protocol that you want to allow.
4. Select Update.

For more information, refer to the Self IP Addresses chapter in the BIG-IP TMOS: Routing Administration guide.

Note: For information about how to locate F5 product manuals, refer to K98133564: Tips for searching AskF5 and finding product
documentation.

iCall authentication and authorization configuration

Assigning iCall administrative rights at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command syntax:

modify auth user <username> role admin

Assigning iCall administrative rights to a user using the Configuration utility

 1. Go to System > Users > User List.
2. Select the user name of the user you want to modify.
3. For Partition Access, for Role, select Administrator.
4. Select Update.

iCall access

iCall is a local event system for the BIG-IP system. It does not have any ports available.

SNMP authentication and authorization configuration

Configuring SNMP at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command:

tmsh help /sys snmp

SNMP automation includes systems and languages external to the BIG-IP system.

Important: There is no user-based authentication or authorization for SNMP. Anyone with access to the port can send and
receive information. Do not expose SNMP to uncontrolled networks.

 
Setting up self IP port lockdown to accept SNMP traffic on port 161

Port lockdown specifies the protocols and services from which a self IP address can accept traffic. It is a security feature that allows
you to specify particular UDP and TCP protocols and services from which the self IP address can accept traffic. By default, a self IP
address accepts traffic from these protocols and services:

For UDP, the allowed protocols and services are: DNS (53), SNMP (161), RIP (520)
For TCP, the allowed protocols and services are: SSH (22), DNS (53), SNMP (161), HTTPS (443), 4353 (iQuery)

You access SNMP on port 161. If self IP addresses are not configured to allow port 161 to receive traffic for SNMP, you need to
configure port lockdown settings.

Configuring self IP port lockdown at the command line

1. Log in to tmsh by entering the following command:

tmsh

2. Enter the following command syntax:

modify net self <name or ip address> allow-service add { tcp:161 }

Configuring self IP port lockdown using the Configuration utility

1. Go to Network > Self IPs.

2. Select the IP address you want to configure.
3. In Port Lockdown, select the port and protocol that you want to allow.
4. Select Finished.

For more information, refer to the Self IP Addresses chapter in the BIG-IP TMOS: Routing Administration guide.
Note: For information about how to locate F5 product manuals, refer to K98133564: Tips for searching AskF5 and finding product
documentation.

BIG-IP TMOS operations guide

Chapter 1: Guide introduction and contents
Chapter 2: Quick Start Guides
Chapter 3: F5 iHealth
Chapter 4: Operating Environment
Chapter 5: Hardware Diagnostics
Chapter 6: VIPRION
Chapter 7: Drive Maintenance
Chapter 8: Licenses and Entitlement
Chapter 9: Backup and Data Recovery
Chapter 10: Software Updates
Chapter 11: Networking and Cluster Health
Chapter 12: Log Files and Alerts
Chapter 13: Modules
Chapter 14: MySQL
Chapter 15: Caches
Chapter 17: Security
Appendix A: Outside the Box
Appendix B: Deployment and Response Methodologies
Appendix C: Support Incident Report

Related Content
About operations guides
Optimizing the support experience
The iApps Home page on F5 Cloud Docs
The iControl (SOAP) Home page on F5 Cloud Docs
The iCall module page on F5 Cloud Docs
The iRules Home page on F5 Cloud Docs
BIG-IP iHealth User Guide
Note: For information about how to locate F5 product manuals, refer to K98133564: Tips for searching AskF5 and finding
product documentation.
Was this information helpful? 

Yes No

How can we improve this content?

May we contact you directly regarding this feedback?

Yes No

Contact Support

HAVE A QUESTION? Support and Sales ›

ABOUT F5 +

EDUCATION +

F5 SITES +

SUPPORT TASKS +

©2023 F5, Inc. All rights reserved.

Policies Privacy Trademarks California Privacy Do Not Sell My Personal Information
MyF5 Terms of Use Cookie Preferences