iControl 101 - #12 - Database Variables

iControl exposes thousands of methods to get and set attributes associated with all of the core object types (Virtuals, Pools, etc).  The API also covers non-core objects such as SNMP and Certificates.  But, there are some settings that are stored in our internal database that are not directly exposed via the API, but that's not to say that they are not "indirectly" exposed.  This article will discuss how to use the Management::DBVariable interface to get at those hidden configuration settings.

Initialization

This article uses PowerShell and the iControl Cmdlets for PowerShell as the client environment for querying the data.  The following setup will be required for the examples contained in this article.

>PS> Add-PSSnapIn iControlSnapIn
PS> Initialize-F5.iControl -Hostname bigip_address -Username bigip_user -Password bigip_pass
PS> $DBVariable = (Get-F5.iControl).ManagementDBVariable

Querying the Data

If you want a quick and dirty dump of all the data that is in the database, you can use the get_list() method that takes no parameters as input and returns an array of name/value pairs contianing the name and value of the variable.

PS> $DBVariable.get_list().Length
472
PS> $DBVariable.get_list()
name                                                        value
----                                                        -----
failover.usetty01                                           enable
gtm.debugprobelogging                                       disable
compression.octeon.dispatchsize                             61170
ucs.loadtime                                                1194541281
switchboard.maxmcastrate                                    200000
switchboard.maxdlfrate                                      200000
switchboard.maxbcastrate                                    200000
...

From the first command you can see that there are quite a few values in there.  If you want to be more specific on the database variables that are returned, you can use the query method to pass in a list of variable names and it will return the name/value pair arrays for output.

PS > $DBVariable.query( ("pva.version", "pva.acceleration") )
name                                                        value
----                                                        -----
pva.version                                                 2
pva.acceleration                                            full

Modifying Variables

Reading a variable is great, but there may be those situations when you'll need to modify that variable.  The following example will illustrate how to modify the internal log settings of the iControl portal.  By allocating a Management::DBVariable::VariableNameValue structure and populating it with the variables to modify, you can call the modify() command to do the work.

PS > $NameValue = new-object -typename iControl.ManagementDBVariableVariableNameValue
PS > # Disable iControl Logging
PS > $NameValue.name = "icontrol.loglevel"
PS > $NameValue.value = "none"
PS > $DBVariable.modify((,$NameValue))

PS > # Enable error level debugging
PS > $NameValue.value = "debug"
PS > $DBVariable.modify((,$NameValue))

PS > # Enable parameter level tracing
PS > $NameValue.value = "trace"
PS > $DBVariable.modify((,$NameValue))

Creating variables

If you find you need to create a variable beyond what's in the database (which I cannot think of an instance, but that's not to say it doesn't exist), then you can use the create() method.  Like the modify() method, this command takes as input an array of Management::DBVariable::VariableNameValue structures with your new variable names and values.  This example will create the variable "JoesVariable" and populate it with "JoeIsCool".

PS > $NameValue = new-object -typename iControl.ManagementDBVariableVariableNameValue
PS > $NameValue.name = "JoesVariable"
PS > $NameValue.value = "JoeIsCool"
PS > $DBVariable.create((,$NameValue))
PS > $DBVariable.query((,"JoesVariable"))
name                                                        value
----                                                        -----
JoesVariable                                                JoeIsCool

Deleting variables

Now, if you accidentally create a variable that you no longer need, you can use the the delete_variable() method that will remvte the specified variable name from the database. 

BEWARE that using this method could get you into serious trouble so use it VERY wisely.  Deleting the wrong database variables can do some really "un-fun" things so please use this method wisely (or better yet, not at all). 

PS > $DBVariable.delete_variable((,"JoesVariable"))
PS > $DBVariable.query((,"JoesVariable"))
Exception calling "query" with "1" argument(s): "Exception caught in Management::DBVariable::query()
Exception: Common::OperationFailed
    primary_error_code   : 16908342 (0x01020036)
    secondary_error_code : 0
    error_string         : 01020036:3: The requested BIGdb variable (joesvariable) was not found."
At line:1 char:18
+ $DBVariable.query( <<<< (,"JoesVariable"))

Conclusion

By exposing the internal database in this manner, it is very simple to look at the internals of the configuration database.  But, as I mentioned before, beware of the dangers when modifying (or deleting) the values in the database as that can lead to undesired results.  With that being said, dig in and do your best not to get yourself into trouble.