HoneyClient::Util::Config - Perl extension to provide a generic interface to the HoneyClient global configuration file.

This documentation refers to HoneyClient::Util::Config version 0.98.

  use HoneyClient::Util::Config qw(getVar);

  my $address = undef;

  # Fetch the value of "address" using the default namespace.
  $address = getVar(name => "address");

  # Fetch the value of "address" using the "HoneyClient::Agent::Driver" namespace.
  $address = getVar(name      => "address", 
                    namespace => "HoneyClient::Agent::Driver");

  # Fetch the value of "address" using the "HoneyClient::Manager" namespace.
  $address = getVar(name      => "address", 
                    namespace => "HoneyClient::Manager");

  # Set the value of "address" using the default namespace
  setVar( name  => 'address',
          value => 'new_address' );

  # Set the value using a specified namespace
  setVar( name      => 'address',
          namespace => 'HoneyClient::Agent::Driver',
          value     => 'new_address' );

This library allows any HoneyClient module to quickly access the global configuration options, associated with this program.

This library makes extensive use of the XML::XPath module.

If $attribute is undefined or not specified, then this function will attempt to retrieve the contents of the element $varName, as it is set within the HoneyClient global configuration file.

If $attribute is defined, then this function will attempt to retrieve specified attribute listed within the contents the contents of the element $varName, as it is set within the HoneyClient global configuration file.

If $caller is undefined or not specified, then this function may return different values, depending upon which module is calling this function.

For example, if module HoneyClient::Agent::Driver calls this function as getVar(name => "address"), then this function will attempt to search for a value like the following, within the global configuration file:

  <HoneyClient>
      <Agent>
          <Driver>
              <address>localhost</address>
          </Driver>
      </Agent>
  </HoneyClient>

If the "address" value is not found at this level within the XML tree, then the function will attempt to locate values, like the following:

# First try:

  <HoneyClient>
      <Agent>
          <address>localhost</address>
      </Agent>
  </HoneyClient>

# Last try:

  <HoneyClient>
      <address>localhost</address>
  </HoneyClient>

This function will stop its recursive search at the first value found, closest to the child module's XML namespace.

Even after performing a recursive search, if no variable name exists, then the function will issue a warning and return undef.

If the variable found is an element that contains child elements, then a corresponding hashtable will be returned. For example, if we perform a getVar(name => "foo") on the following XML:

  <HoneyClient>
      <foo>
          <bar>123</bar>
          <bar>456</bar>
          <yok>789</yok>
          <yok>xxx</yok>
      </foo>
  </HoneyClient>

Then the following $hashref will be returned:

  $hashref = {
      'bar' => [ '123', '456' ],
      'yok' => [ '789', 'xxx' ],
  }

Inputs:$varName is the variable name to search for, within the global configuration file.$caller is an optional argument, signifying the module namespace to use, when searching for the variable's value.$attribute is an optional argument, signifying that the function should return the attribute associated with the variable's element.

Output: The variable's element/attribute value or hashtable (for multi-value elements), if found; warns and returns undef otherwise.

Note: If the target variable to return is an element that contains combinations of text and sub-elements, then only the text within the sub-elements will be returned in the previously mentioned $hashref format.

For example, if we perform a getVar(name => "foo") on the following XML:

  <HoneyClient>
      <foo>
          THIS_TEXT_WILL_BE_LOST
          <bar>123</bar>
          <bar>456</bar>
          <yok>789</yok>
          <yok>xxx</yok>
          <yok><CHILD>zzz</CHILD></yok>
      </foo>
  </HoneyClient>

Then the following $hashref will be returned:

  $hashref = {
      'bar' => [ '123', '456' ],
      'yok' => [ '789', 'xxx', 'zzz' ],
  }

Notice how the THIS_TEXT_WILL_BE_LOST string got dropped and that the <CHILD> tags were silently stripped from the zzz string. In other words, in each target element, don't mix text with sub-elements and don't nest sub-elements if you want the nested structure preserved when a getVar() is called on the grandparent element.

This will set the desired value. If the required attribute or element does not exist, it (and any parents) will be created

Inputs:$varName is the variable name to search for, within the global configuration file.$caller is an optional argument, signifying the module namespace to use, when searching for the variable's value.$attribute is an optional argument, signifying that the function should return the attribute associated with the variable's element.$value is the value to set the element or attribute to

This module assumes the HoneyClient global configuration file is located in: /etc/honeyclient_log.conf

The getVar($varName) function will attempt to get a module-specific variable setting, first. If that setting is not specified, the function call will recursively search for the same variable located within any parent (or global) regions of the configuration file.

Furthermore, getVar() returns hashrefs for target elements that contain additional child sub-elements. However, the format of this hashref is NOT necessarily intuitive. See the getVar() documentation for further details.

http://www.honeyclient.org/trac

XML::XPath

http://www.honeyclient.org/trac/newticket

Darien Kindlund, <kindlund@mitre.org>

Fotios Lindiakos, <flindiakos@mitre.org>

Copyright (C) 2007 The MITRE Corporation. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, using version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.