iControl Apps - #12 - Global SSL Statistics

Continuing on with my series of applications on system level statistics, this application will look into the insides of the SSL subsystem and dump out the available statistics for client and server based SSL processing.

Usage

The arguments for this application are the address, username, and password of the BIG-IP.  This is declared in the top of the script with the following param statement.  There is also a Write-Usage function to display the arguments to the user.

param (
  $g_bigip = $null,
  $g_uid = $null,
  $g_pwd = $null
);

Set-PSDebug -strict;

function Write-Usage()
{
  Write-Host "Usage: GlobalSSLStats.ps1 host uid pwd";
  exit;
}

Initialization

As is with all of my PowerShell scripts, the initialization component will look to see if the iControlSnapIn is loaded into the current PowerShell session.  If not, the Add-PSSnapIn Cmdlet is called to add the snapin into the runtime.  Then a call to the Initialize-F5.iControl cmdlet to setup the connection to the BIG-IP.  If this succeeds, then a call to the Get-GlobalSSLStatistics function is called to query the client and server SSL Statistics and output them to the console.

function Do-Initialize()
{
  if ( (Get-PSSnapin | Where-Object { $_.Name -eq "iControlSnapIn"}) -eq $null )
  {
    Add-PSSnapIn iControlSnapIn
  }
  $success = Initialize-F5.iControl -HostName $g_bigip -Username $g_uid -Password $g_pwd;
  
  return $success;
}

#-------------------------------------------------------------------------
# Main Application Logic
#-------------------------------------------------------------------------
if ( ($g_bigip -eq $null) -or ($g_uid -eq $null) -or ($g_pwd -eq $null) )
{
  Write-Usage;
}

if ( Do-Initialize )
{
  Get-GlobalSSLStatistics;
}
else
{
  Write-Error "ERROR: iControl subsystem not initialized"
}

Querying SSL Statistics

The SSL statistics are broken into two parts, the client and server.  The client SSL profiles handle the connection between the client and the BIG-IP while the server SSL profiles handle the connection between the BIG-IP and the backend server.  In this example, I've combined the two statistics into a single display.  In the following code both the client and server statistics are retrieved witht the get_client_sll_statistics and get_server_ssl_statistics methods repectively.  The next step is to combine the two side by side for a nice display.  Previously I've use the Add-Member cmdlet to dynamically add fields to an empty object for easy display through the format-list cmdlet.  In this example, I will use a PowerShell hash to store the name/value pairs.

In the first loop, each of the client side SSL statistics are examined, first converting the data into a native 64 bit number and then calling the local Get-StatisticLabel function to conver the default enumaration type to a user friendly name.  This label and the 64 bit value are then added to the hash table.

In the second loop, the server side SSL statstistics are examined much like the client side statistics except in this case the hash is overwritten with the both the client and server values so that we can get a nice side by side display of each statistic value.

Finally the hash's enumerator is retrieved with the GetEnumerator() function on the hash table and that value is passed through an ascii sort and then formatted with the Format-Table cmdlet.

function Get-GlobalSSLStatistics()
{
  $SystemStatisticsClient = (Get-F5.iControl).SystemStatistics.get_client_ssl_statistics();
  $SystemStatisticsServer = (Get-F5.iControl).SystemStatistics.get_server_ssl_statistics();
  $t = Get-TimeFromTimeStamp $SystemStatisticsClient.time_stamp;
 
  $hash = @{};
 
  $hash.Add("* Time Stamp", $t);
  $hash.Add("* Type", "(Client, Server)");
 
  $Statistics = $SystemStatisticsClient.statistics;
  foreach($Statistic in $Statistics)
  {
    $val = Convert-To64Bit $Statistic.value.high $Statistic.value.low;
    $label = Get-StatisticLabel $Statistic.type;
    $hash.Add($label, $val);
  }

  $Statistics = $SystemStatisticsServer.statistics;
  foreach($Statistic in $Statistics)
  {
    $val = Convert-To64Bit $Statistic.value.high $Statistic.value.low;
    $label = Get-StatisticLabel $Statistic.type;
   
    $v1 = $hash[$label];
    $hash[$label] = "($v1, $val)";
  }
  $hash.GetEnumerator() | Sort-Object -Property Name | Format-Table -autosize
}

function Get-StatisticLabel()
{
  param($type);
  $label = "";
 
  switch($type)
  {
    "STATISTIC_SSL_COMMON_CURRENT_CONNECTIONS" {
      $label = "Connections - currently Opened";
    }
    "STATISTIC_SSL_COMMON_MAXIMUM_CONNECTIONS" {
      $label = "Connections - maximum simultaneous";
    }
    "STATISTIC_SSL_COMMON_CURRENT_NATIVE_CONNECTIONS" {
      $label = "Connections - currently opened native";
    }
    "STATISTIC_SSL_COMMON_MAXIMUM_NATIVE_CONNECTIONS" {
      $label = "Connections - maximum simultaneous native";
    }
    "STATISTIC_SSL_COMMON_TOTAL_NATIVE_CONNECTIONS" {
      $label = "Connections - total native";
    }
    "STATISTIC_SSL_COMMON_CURRENT_COMPATIBLE_MODE_CONNECTIONS" {
      $label = "Connections - currently opened compatible mode";
    }
    "STATISTIC_SSL_COMMON_MAXIMUM_COMPATIBLE_MODE_CONNECTIONS" {
      $label = "Connections - maximum compatible mode";
    }
    "STATISTIC_SSL_COMMON_TOTAL_COMPATIBLE_MODE_CONNECTIONS" {
      $label = "Connections - total compatible mode";
    }
    "STATISTIC_SSL_COMMON_ENCRYPTED_BYTES_IN" {
      $label = "Bytes - total encrypted received";
    }
    "STATISTIC_SSL_COMMON_ENCRYPTED_BYTES_OUT" {
      $label = "Bytes - total encrypted sent";
    }
    "STATISTIC_SSL_COMMON_DECRYPTED_BYTES_IN" {
      $label = "Bytes - total decrypted received";
    }
    "STATISTIC_SSL_COMMON_DECRYPTED_BYTES_OUT" {
      $label = "Bytes - Total decrypted sent";
    }
    "STATISTIC_SSL_COMMON_RECORDS_IN" {
      $label = "Records - total received";
    }
    "STATISTIC_SSL_COMMON_RECORDS_OUT" {
      $label = "Records - total sent";
    }
    "STATISTIC_SSL_COMMON_FULLY_HW_ACCELERATED_CONNECTIONS" {
      $label = "Connections - total offloaded";
    }
    "STATISTIC_SSL_COMMON_PARTIALLY_HW_ACCELERATED_CONNECTIONS" {
      $label = "Connections - total assisted";
    }
    "STATISTIC_SSL_COMMON_NON_HW_ACCELERATED_CONNECTIONS" {
      $label = "Connections - total software";
    }
    "STATISTIC_SSL_COMMON_PREMATURE_DISCONNECTS" {
      $label = "Shutdowns - total unclean";
    }
    "STATISTIC_SSL_COMMON_MIDSTREAM_RENEGOTIATIONS" {
      $label = "Hanshakes - total mid-connection";
    }
    "STATISTIC_SSL_COMMON_SESSION_CACHE_CURRENT_ENTRIES" {
      $label = "Cache - current session entries";
    }
    "STATISTIC_SSL_COMMON_SESSION_CACHE_HITS" {
      $label = "Cache - total hits";
    }
    "STATISTIC_SSL_COMMON_SESSION_CACHE_LOOKUPS" {
      $label = "Cache - total lookups";
    }
    "STATISTIC_SSL_COMMON_SESSION_CACHE_OVERFLOWS" {
      $label = "Cache - total overflows";
    }
    "STATISTIC_SSL_COMMON_SESSION_CACHE_INVALIDATIONS" {
      $label = "Cache - total session invalidations";
    }
    "STATISTIC_SSL_COMMON_VALID_PEER_CERTIFICATES" {
      $label = "Certificates - total valid";
    }
    "STATISTIC_SSL_COMMON_INVALID_PEER_CERTIFICATES" {
      $label = "Certificates - total invalid";
    }
    "STATISTIC_SSL_COMMON_NO_PEER_CERTIFICATES" {
      $label = "Certificates - connections without";
    }
    "STATISTIC_SSL_COMMON_HANDSHAKE_FAILURES" {
      $label = "Handshake - total failures";
    }
    "STATISTIC_SSL_COMMON_NOT_SSL_HANDSHAKE_FAILURES" {
      $label = "Handshake - total bad client greetings";
    }
    "STATISTIC_SSL_COMMON_BAD_RECORDS" {
      $label = "Records - total bad";
    }
    "STATISTIC_SSL_COMMON_FATAL_ALERTS" {
      $label = "Alerts - total fatal";
    }
    "STATISTIC_SSL_PROTOCOL_SSLV2" {
      $label = "Protocol - total SSLv2";
    }
    "STATISTIC_SSL_PROTOCOL_SSLV3" {
      $label = "Protocol - total SSLv3";
    }
    "STATISTIC_SSL_PROTOCOL_TLSV1" {
      $label = "Protocol - total TLSv1";
    }
    "STATISTIC_SSL_CIPHER_ADH_KEY_EXCHANGE" {
      $label = "Key Exchange - total anonymous Diffie-Hellman";
    }
    "STATISTIC_SSL_CIPHER_DH_RSA_KEY_EXCHANGE" {
      $label = "Key Exchange - total Diffie-Hellman w/RSA certificate";
    }
    "STATISTIC_SSL_CIPHER_EDH_RSA_KEY_EXCHANGE" {
      $label = "Key Exchange - ephemeral Diffie-Hellman w/RSA certificate";
    }
    "STATISTIC_SSL_CIPHER_RSA_KEY_EXCHANGE" {
      $label = "Key Exchange - RSA cerficate";
    }
    "STATISTIC_SSL_CIPHER_NULL_BULK" {
      $label = "Cipher - No encryption";
    }
    "STATISTIC_SSL_CIPHER_AES_BULK" {
      $label = "Cipher - Advanced Encryption Standard (AES)";
    }
    "STATISTIC_SSL_CIPHER_DES_BULK" {
      $label = "Cipher - Digital Encryption Standard (DES)";
    }
    "STATISTIC_SSL_CIPHER_IDEA_BULK" {
      $label = "Cipher - IDEA (old SSLv2)";
    }
    "STATISTIC_SSL_CIPHER_RC2_BULK" {
      $label = "Cipher - Rivest Cipher 2";
    }
    "STATISTIC_SSL_CIPHER_RC4_BULK" {
      $label = "Cipher - Rivest Cipher 4";
    }
    "STATISTIC_SSL_CIPHER_NULL_DIGEST" {
      $label = "Cipher - No message authentication";
    }
    "STATISTIC_SSL_CIPHER_MD5_DIGEST" {
      $label = "Cipher - Message Digest 5 (MD5)";
    }
    "STATISTIC_SSL_CIPHER_SHA_DIGEST" {
      $label = "Cipher - Secure Hash Algorithm (SHA)";
    }
    default {
      $label = "***UNKNOWN***";
    }
  }
  return $label;
}

Running the code

The following command line will execute the code and display the output.  Since I do not have any ssl terminated virtuals on my test system, the data here is pretty boring.  But, give it a shot on your active site and you'll see the data presented.

PS C:\> .\GlobalSSLStats.ps1 bigip_address username password

Name                                                      Value
----                                                      -----
* Time Stamp                                              10/6/2008 1:03:54 PM
* Type                                                    (Client, Server)
Alerts - total fatal                                      (0, 0)
Bytes - total decrypted received                          (0, 0)
Bytes - Total decrypted sent                              (0, 0)
Bytes - total encrypted received                          (0, 0)
Bytes - total encrypted sent                              (0, 0)
Cache - current session entries                           (0, 0)
Cache - total hits                                        (0, 0)
Cache - total lookups                                     (0, 0)
Cache - total overflows                                   (0, 0)
Cache - total session invalidations                       (0, 0)
Certificates - connections without                        (0, 0)
Certificates - total invalid                              (0, 0)
Certificates - total valid                                (0, 0)
Cipher - Advanced Encryption Standard (AES)               (0, 0)
Cipher - Digital Encryption Standard (DES)                (0, 0)
Cipher - IDEA (old SSLv2)                                 (0, 0)
Cipher - Message Digest 5 (MD5)                           (0, 0)
Cipher - No encryption                                    (0, 0)
Cipher - No message authentication                        (0, 0)
Cipher - Rivest Cipher 2                                  (0, 0)
Cipher - Rivest Cipher 4                                  (0, 0)
Cipher - Secure Hash Algorithm (SHA)                      (0, 0)
Connections - currently Opened                            (0, 0)
Connections - currently opened compatible mode            (0, 0)
Connections - currently opened native                     (0, 0)
Connections - maximum compatible mode                     (0, 0)
Connections - maximum simultaneous                        (0, 0)
Connections - maximum simultaneous native                 (0, 0)
Connections - total assisted                              (0, 0)
Connections - total compatible mode                       (0, 0)
Connections - total native                                (0, 0)
Connections - total offloaded                             (0, 0)
Connections - total software                              (0, 0)
Handshake - total bad client greetings                    (0, 0)
Handshake - total failures                                (0, 0)
Hanshakes - total mid-connection                          (0, 0)
Key Exchange - ephemeral Diffie-Hellman w/RSA certificate (0, 0)
Key Exchange - RSA cerficate                              (0, 0)
Key Exchange - total anonymous Diffie-Hellman             (0, 0)
Key Exchange - total Diffie-Hellman w/RSA certificate     (0, 0)
Protocol - total SSLv2                                    (0, 0)
Protocol - total SSLv3                                    (0, 0)
Protocol - total TSLv1                                    (0, 0)
Records - total bad                                       (0, 0)
Records - total received                                  (0, 0)
Records - total sent                                      (0, 0)
Shutdowns - total unclean                                 (0, 0)

Conclusion

As with all the other methods in the System.Statistics interface, you'll find a lot of hidden data that you may or may not be aware of.  Explore these global ssl statistics methods and all the others to help you monitor and manage your systems.

The full application can be found in the iControl CodeShare under PsGlobalSslStatistics.