View on GitHub

iHAC

:heart_decoration: iHealth API clients - simple shell scripts to interact with the F5 iHealth API (ihealth.f5.com)

iHAC

ci-tests Releases Commits since latest release Latest Release

About

The iHAC (iHealth API Clients) script collection aims to be a simple and easy to use interface to a subset of features provided by F5 iHealth.

Feature Overview

Demo!

Installation

1. Install prerequisites

This is the list of prerequisites:

BIG-IP 11.x: Works right away

Mac OS: Works right away

Ubuntu / Debian: apt-get install libxml-simple-perl

RedHat / CentOS: yum install perl-XML-Simple

Cygwin: Install curl and perl-XML-Simple through the Cygwin Setup

2. Download / Install / Update

On BIG-IP

simon@bigip ~ $ INSTALLDIR=$HOME/bin; \
	test -d $INSTALLDIR || mkdir -p $INSTALLDIR; \
	CURL_CA_BUNDLE=/config/ssl/ssl.crt/ca-bundle.crt \
	curl -L https://github.com/simonkowallik/iHAC/tarball/main \
	| tar xzv --strip-components 1 --wildcards -C $INSTALLDIR; \
	chmod a+x $INSTALLDIR/ihac

Homebrew / Linuxbrew

simon@macos ~ $ brew install simonkowallik/f5/ihac

If you want to receive updates when running brew update add my tap with brew tap simonkowallik/f5.

On Mac OS

simon@macos ~ $ sudo sh -c 'INSTALLDIR=/usr/local/bin; \
	test -d $INSTALLDIR || mkdir -p $INSTALLDIR; \
	curl -L https://github.com/simonkowallik/iHAC/tarball/main \
	| tar xzv --strip-components 1 -C $INSTALLDIR; \
	chmod a+x $INSTALLDIR/ihac'

Other platforms

simon@other ~ $ INSTALLDIR=/usr/local/bin; \
	test -d $INSTALLDIR || mkdir -p $INSTALLDIR; \
	curl -L https://github.com/simonkowallik/iHAC/tarball/main \
	| tar xzv --strip-components 1 --wildcards -C $INSTALLDIR; \
	chmod a+x $INSTALLDIR/ihac

Adjust INSTALLDIR to your needs. /usr/local/bin is mounted as read-only on BIG-IP therefore the default above is $HOME/bin which is in PATH by default.

If you just want to get the tarball:

simon@bigip ~ $ curl -L https://github.com/simonkowallik/iHAC/tarball/main -o $HOME/ihac.tgz

If the CA chain validation for github.com fails on your system, you might try the following:

  1. Specify an alternative CA bundle by setting CURL_CA_BUNDLE= shell variable (see BIG-IP example above)
  2. Add the -k option to curl to ignore any validity checks, however this is not recommended.

If you need a proxy, use curls proxy option -x http://192.0.2.245:8080.

3. Run

Have fun. :)

Usage

ihac auth

Interactive authentication

simon@bigip ~ $ ihac authV1
Username: simon@example.com
Password:
OK

simon@bigip ~ $ ihac auth
Client ID: i00000OiJpUndzU0RJRW
Client Secret: 
OK

JSON formatted credentials as an argument (authV1)

simon@bigip ~ $ ihac authV1 '{"user_id": "simon@example.com", "user_secret": "MyP@ssw0rd"}'
OK

client ID and client Secret as an argument for iHealth2

simon@bigip ~ $ ihac auth 'client_id:client_secret'
OK

JSON formatted credentials via STDIN

simon@bigip ~ $ cat $HOME/credentials.json | ihac authV1

simon@bigip ~ $ cat $HOME/credentials.json
{"user_id": "simon@example.com", "user_secret": "MyP@ssw0rd"}

De-authenticate / delete session cookies

simon@bigip ~ $ ihac authV1 [--delete | -d | delete | --logout]
OK

ihac qkviewadd

Adds qkview to iHealth, qkview file supplied as argument. You can specify as many qkviews as arguments as you want.

simon@bigip ~ $ ihac qkviewadd ../bigip1141.qkview ./bigip1151.qkview bigip1160.qkview
################################################################## 100.0%
2257810 OK
################################################################## 100.0%
2257812 OK
################################################################## 100.0%
2257814 OK

Adds qkview to iHealth, qkview file supplied via STDIN

simon@bigip ~ $ cat ../qkviews/bigip1151.qkview | ihac qkviewadd
################################################################## 100.0%
2257819 OK

ihac qkviewlist

Lists all qkviews available on iHealth

simon@bigip ~ $ ihac qkviewlist
2257819 bigip1151.example.com SerialNumber	  May 8 2014, 21:12:29 AM (GMT) OptionalCaseNumber
2257811 bigip1151.example.com SerialNumber	  May 8 2014, 21:10:19 AM (GMT) OptionalCaseNumber
2254055 bigip1151.example.com SerialNumber	  May 7 2014, 20:59:32 AM (GMT) OptionalCaseNumber
2254011 bigip1151.example.com SerialNumber	  May 7 2014, 20:32:39 AM (GMT) OptionalCaseNumber

The first column displays the qkview ID, which is important for all commands below.

ihac qkviewget

Dowloads qkview from iHealth, output file specified as argument

simon@bigip ~ $ ihac qkviewget 2254055 ../qkview/2254055.qkview.tgz
################################################################## 100.0%
OK

simon@bigip ~ $ ls -la 2254055.qkview.tgz
-rw-r--r-- 1 simon users 12555744 May  8 21:18 ../qkview/2254055.qkview.tgz

Dowloads qkview from iHealth, outputs to STDOUT

simon@bigip ~ $ ihac qkviewget 2254011 | gzip -d > 2254011.qkview.tar
################################################################## 100.0%
OK

simon@bigip ~ $ ls -la 2254011.qkview.tar
-rw-r--r-- 1 simon users 136547328 May  8 21:23 2254011.qkview.tar

ihac qkviewdelete

Deletes qkview from iHealth. You can specify as many qkview IDs as arguments as you want.

simon@bigip ~ $ ihac qkviewdelete 2257810 2257812
2257810 OK
2257812 OK

ihac filelist

Lists all files for a specific qkview, outputs filenames with path to STDOUT

simon@bigip ~ $ ihac filelist 2254055 | grep /config/bigip | head -5
/config/bigip_base.conf.bak
/config/bigip.conf.bak
/config/bigip_script.conf.bak
/config/bigip_base.conf
/config/bigip.conf

ihac fileget

Get file from qkview on iHealth, outputs file content to STDOUT

simon@bigip ~ $ ihac fileget 2254055 /config/bigip.conf | head
#TMSH-VERSION: 11.5.1

apm client-packaging /Common/client-packaging { }
apm resource remote-desktop citrix-client-bundle /Common/default-citrix-client-bundle { }
ltm default-node-monitor {
    rule none
}
ltm node /Common/10.0.0.10 {
    address 10.0.0.10
}

fetching multiple files (supports wildcards) and placing them in a directory

simon@bigip ~ $ ihac fileget 2254055 --output-directory ./qkview/ /config/bigip*.conf /PLATFORM
simon@bigip ~ $ find ./qkview/ -type f
./qkview/config/bigip_user.conf
./qkview/config/bigip_base.conf
./qkview/config/bigip.conf
./qkview/PLATFORM

ihac commandlist

Lists all commands available for a specific qkview, outputs command list to STDOUT

simon@bigip ~ $ ihac commandlist 2254055 | grep /sys | head
show running-config /sys management-ip
show running-config /sys management-route all-properties
list /sys application service recursive all-properties
list /sys cluster all-properties
list /sys daemon-ha all-properties
list /sys db all-properties
list /sys db all-properties (non-default values)
list /sys db systemauth.source all-properties
list /sys disk all-properties
list /sys feature-module all-properties

ihac commandrun

Fetches command output from qkview on iHealth to STDOUT

simon@bigip ~ $ ihac commandrun 2254055 ‘show /sys provision’
-------------------------------------------------------------
Sys::Provision
Module   CPU (%)   Memory (MB)   Host-Memory (MB)   Disk (MB)
-------------------------------------------------------------
afm            1           466                720        3900
am             0             0                  0           0
apm            0             0                  0           0
asm            0             0                  0           0
avr            0             0                  0           0
em             0             0                  0           0
gtm            0             0                  0           0
host          10          2896                  0       47984
lc             0             0                  0           0
ltm            1             0                  0           0
tmos          88          4640                280           0
ui             0           224                  0           0
vcmp           0             0                  0           0

simon@bigip ~ # ihac commandrun 2254055 'tmctl -a (blade)' | wc -l
4757

ihac diagnostics

Fetch iHealth Diagnostics and output to STDOUT

simon@bigip ~ $ ihac diagnostics 2254055 | head
Hostname: bip1141.example.net    Serial: Serial Number
Version: Version		  	     Platform: Platform

* Severity: LOW/MEDIUM/HIGH	Heuristic: Heuristic Number
* Title:        Heuristic Title
* Summary:      Heuristic Summary
* SOLs:         Link to SOL article

Filter for Severity with egrep

simon@bigip ~ $ ihac diagnostics 2254055 | egrep -A3 "MEDIUM|^(P|H)"
simon@bigip ~ $ ihac diagnostics 2254055 | egrep -A3 "HIGH|MEDIUM|^(P|H)"

Output JSON or XML for further processing

simon@bigip ~ $ ihac diagnostics --json 2254055 | jq .
simon@bigip ~ $ ihac diagnostics --xml 2254055 | xq

Proxy Support

Specify environment variable before executing an ihac script

simon@bigip ~ $ IHACPROXY=http://localhost:8080 ihac *

Set environment variable which is then used by all further ihac scripts executed in the same session

simon@bigip ~ $ export IHACPROXY=http://localhost:8080
simon@bigip ~ $ ihac *

Set a permanent proxy

simon@bigip ~ $ echo ‘http://localhost:8080’ > $HOME/.ihac/IHACPROXY
simon@bigip ~ $ ihac *

Note: Environment variable will always have precedence

Security

Transport Security

cURL command line client is used to interact with iHealth. Transport security depends on cURL, which includes encryption and authenticity verification.

Credentials and iHealth session cookies

Credentials are never stored on disk, unless a user decides to. iHealth session cookies will be stored in $HOME/.ihac/auth.jar, which is valid for about 4 hours.

Session cookie jar file is only readable and writable by user.

simon@bigip ~ $ file $HOME/.ihac/auth.jar
/home/simon/.ihac/auth.jar: Netscape cookie, ASCII text

simon@bigip ~ $ ls -l $HOME/.ihac/
total 4
-rw------- 1 simon users 1531 May 11 23:37 auth.jar

Session cookies can be deleted by ihac auth or manually by the user.

simon@bigip ~ $ ihac auth --logout
OK

simon@bigip ~ $ file $HOME/.ihac/auth.jar
/home/simon/.ihac/auth.jar: empty

simon@bigip ~ $ rm -f $HOME/.ihac/auth.jar

iHealth2 API access_token

The access_token is valid for 1800 seconds and stored in $HOME/.ihac/auth_token.txt.

Usage Examples

Pipe credentials from local to remote system for authentication and list all qkviews available on iHealth

~ $ cat $HOME/auth.txt | ssh root@192.168.1.245 '/root/bin/ihac auth;/root/bin/ihac qkviewlist'
Password:
OK
2483776 bigip.example.com           0570271                Jun 30 2014, 06:59:43 PM (GMT)
2483760 bigip.example.com           0570271                Jun 30 2014, 06:54:47 PM (GMT)

Pipe local qkview file to remote system and upload to iHealth

~ $ cat qkview/bigip1141.qkview.tgz | ssh root@192.168.1.245 '/root/bin/ihac qkviewadd'
Password:
################################################################## 100.0%
OK

Get file from iHealth and send to remote system

~ $ ihac fileget 2521684 /config/bigip.conf | ssh root@192.168.1.245 'cat > /tmp/bigip.conf'

Generate qkview on remote system, send via pipe to local system and upload to iHealth

~ $ ssh root@192.168.1.245 'qkview -f /var/tmp/qkview.tgz;cat /var/tmp/qkview.tgz' | ihac qkviewadd
Password:
Gathering System Diagnostics: Please wait ...
Diagnostic information has been saved in:
/var/tmp/qkview.tgz
Please send this file to F5 support.
################################################################## 100.0%
OK