iControl REST + jq Cookbook - Readme

This series describes convenient methods for extracting meaningful information from lengthy and often verbose iControl REST responses using a third party tool called jq.

To extract specific data from an iControl REST JSON text response, such as a virtual server name or pool member IP address, most often, you would try good old Unix utilities such as grep, sed or awk. You would pipe multiple commands if a single command does not satisfy you. If you have ever craved for a neater way, consider using jq - A tool specifically designed for parsing and filtering JSON texts.

jq is bundled with BIG-IP. If your client system does not have one, you can install it via a package management tool such as yum or apt. Alternatively, you can download the binary from Download jq. You can copy it to any directory as it does not have any dependency.

Although jq for Windows is available, Windows command prompt is picky about quotes and escapes. The jq filter examples in the documents are for bash, hence you may need to tweak them to satisfy peculiar Window's needs. Consider enabling Windows Subsystem for Linux (WSL) to use bash on Windows.

If you are unfamiliar with JSON, please take a look at RFC 8259: "The JavaScript Object Notation (JSON) Data Interchange Format". Don't worry. It's just 16 pages long.

Table of Contents

• Part01 - Basics
• Format the entire JSON body
• Sort by property names
• Extract a specific property
• Error
• Substitute the authentication token to a shell variable
• Extract multiple properties
• Format the output
• Count a number of objects
• Iterate through an array
• Obtain the full pool information
• Part02 - Intermediate [To be published]
• Extract an array element
• Slice an array
• Find the element
• Find matching elements
• Extract property names and values
• Extract a property from deeply nested object
• Tabularize all the version information
• Process raw monitor output
• Format 'list sys global-settings' output
• Convert Unix epoch time
• Part03 - Advanced topics [To be published]
• Replicate an object with slight modifications
• Modify internal data-group records
• Process restjavad-autit.log
• Process restjavad-api-usage.log
• Get a list of the latest Automation Toolchain

Examples

The examples in this series use curl for sending iCotnrol REST requests. The response JSON body is fed into the jq's stdin via pipe as below.

curl -sku admin:admin https://<host>/mgmt/tm/sys/version | jq '.'

The -s curl option is for disabling its progress bar (--silent). The -k option is for skipping server certificate verification (--insecure). The -u is to provide the user name and password (--user): The examples use the user 'admin' with the password 'admin'. Please change them. The <host> in the URL is the management IP of the target BIG-IP.

The example output is shown directly below the call:

curl -sku $PASS https://$HOST/mgmt/tm/sys/version | jq '.'
{                               # output starts from here
 "kind": "tm:sys:version:versionstats",
 "selfLink": "https://localhost/mgmt/tm/sys/version?ver=15.1.2",
 "entries": {
  "https://localhost/mgmt/tm/sys/version
  ...                            # Skipped

References

• jq 1.6 Manual. The current latest version is 1.6. The one bundled in BIG-IP is 1.5. 
• Download jq.
• curl.1 the man page.
• iControl REST Home, F5 Clouddocs.
• iControl REST Cookbook - Virtual Server (ltm virtual), Devcentral.
• iControl REST Cookbook - LTM policy (ltm policy), DevCentral.
• iControl REST Cookbook - Virtual Server Profile (LTM Virtual Profiles), DevCentral.
• K13225405: Common iControl REST API command examples, AskF5.
• The JavaScript Object Notation (JSON) Data Interchange Format, RFC 8259, IETF.
• Windows Subsystem for Linux, Microsoft.