M. Lawrence Weikum > BGPmon-core-1-092 > BGPmon::Configure

Download:
BGPmon-core-1-092.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 1.092   Source  

NAME ^

BGPmon::Configure - BGPmon Client Configuration

This module sets initial configuration variables from a combination of default values, configuration file parameters, and command line options.

SYNOPSIS ^

The module allows one to specify a set of configuration parameters and the module sets these parameters based on a cominbation of default vaules, command line options, and configuration file settings. The module does the work of parsing the commmand line, generating any usage messages, and reading a configuration file. You simply specify the input paramters you would like to allow in the configuation file and on the commmand line.

To specify a parameter, you must provide a parameter Name and parameter Type. Possible Types are ADDRESS, PORT, FILE, BOOLEAN, STRING, and UNSIGNED_INT.

Once you have specified the paramters, the configure function will take care of generating command line arguements and will generate any usage errors if the user does not specify correct command line options.

You may optionally specify a Description and your description text will appear after this option in any Usage message.

The configure function will also read from a configuration file. Note that values set by the command line take precedence and over-ride any settings found in the configuration file. The user can specify the configuration file with -c file or with -config_file file.

You may also specify a Default configuration file or specify a Default for any other option. Settings found in the configutaion file and command line take precedence over any default settings.

Once you have specified your parameters and called configure(%your_params), you can use get_paramter("param_name") to get the value of any paramter. You can also call parameter_set_by("param_name") to see if the parameter was set using the default, the config file, or the command line (or was not set at all).

Finally, if you want to later over-ride any parameter, you can set it to a value using set_parameter("param_name", value). This is not recommended. You should rely on your defaults, the config file, and the command line to set your parameters. But set_parameter is provided as option in case special cases need it.

Example:

use BGPmon::Configure; # lets define some parameters for my program my @params = ( { Name => BGPmon::Configure::CONFIG_FILE_PARAMETER_NAME, Type => BGPmon::Configure::FILE, Default => "./foo", Description => "this is the configuration file name", }, { Name => "server", Type => BGPmon::Configure::ADDRESS, Default => "127.0.0.1", Description => "this is the server address", }, { Name => "port", Type => BGPmon::Configure::PORT, Default => 50002, Description => "this is the server port", }, { Name => "output_file", Type => BGPmon::Configure::FILE, Default => "/tmp/file", Description => "My Output File", }, { Name => "use_syslog", Type => BGPmon::Configure::BOOLEAN, Description => "Use Syslog for error checking", }, { Name => "somestring", Type => BGPmon::Configure::STRING, Default => "This is a string used for something", }, { Name => "log_level", Type => BGPmon::Configure::UNSIGNED_INT, Default => 7, } );

# now tell the module to set those parameters

if (BGPmon::Configure::configure(@params) ) { my $code = BGPmon::Configure::get_error_code("configure"); my $msg = BGPmon::Configure::get_error_message("configure"); print "Error Code is $code and message is $msg \n"; exit; }

# let's see what parameter "server" got set to

my $srv = BGPmon::Configure::parameter_value("server"); if (defined($srv)) { print "The server parameter was set to $srv\n"; }

# let's see how parameter "server" was set

my $setby = BGPmon::Configure::parameter_set_by("server"); if ($setby == BGPmon::Configure::NOT_SET) { print "The server parameter has not been set\n"; } elsif ($setby == BGPmon::Configure::DEFAULT) { print "The server parameter was set to the default value \n"; } elsif ($setby == BGPmon::Configure::COMMAND_LINE) { print "The user set the server parameter from the command line\n"; } elsif ($setby == BGPmon::Configure::CONFIG_FILE) { print "The server parameter was set in the configuration file\n"; } elsif ($setby == BGPmon::Configure::SET_ERROR) { print "something went wrong... the parameter has an error\n"; }

# this is not recommended, but we can over-ride that setting and change the parameter value

my $new_srv = "127.0.0.1";

if (BGPmon::Configure::set_parameter("server", $new_srv) ) { my $code = BGPmon::Configure::get_error_code("set_parameter"); my $msg = BGPmon::Configure::get_error_message("set_parameter"); print "Error Code is $code and message is $msg \n"; exit; }

if (BGPmon::Configure::parameter_set_by("server") == BGPmon::Configure::SET_FUNCTION ) { print "I over-rode everything and set the server parameter to $new_srv\n"; }

EXPORT ^

configure parameter_value parameter_set_by set_parameter

SUBROUTINES/METHODS ^

configure

set initial configuration variables from a combination of default values, configuration file parameters, and command line options

Input : an array of hashes that specify the configuration parameters. Each configuration parameter is represented by one hash with elements: 1. Name - (required) the name of the paramter as it will appear in the command line and configuration file 2. Type - (required) the type of value associated with this name. supported types include address, port, boolean, unsigned integer. 3. Default (optional) - the default value to associate with this parameter if it is not found in the config file or command line 4. Description (optional) - A description to appear in a usage message

Output: 0 on success, 1 on error and error code and error message are set

parameter_value

Return the setting for a configuraion parameter

Input : the name of the paramter

Output: the value of the parameter. if the input name does not correspond to a parameter, the function returns undef and sets error code and error message

parameter_set_by

 indicates how the parameter value was set.   
Input : the name of the paramter
Output:  one of the following codes indicating how the parameter was set:
    - not set at all (NOT_SET), 
    - set to a default value (DEFAULT), 
    - set by the command line (COMMAND_LINE),  
    - set by the configuraiton file (CONFIG_FILE),  
    - set externally using the set_paramater function (SET_FUNCTION)
    - or  on error,  (SET_ERROR) and the error_code and error_message are set

set_parameter

 Sets a parameter to the specified value.  

 Configuration parameters are typically set by a combination of default value,  
 command line options, and configuration file options.   This function allows 
 the caller to over-ride all this and force a parameter to the specified value.

Input : the name of the paramter and the value for the paramter Output: 0 on success, 1 on error and sets error_code and error_message

get_error_code

Get the error code Input : the name of the function whose error code we should report Output: the function's error code or NO_FUNCTION_SPECIFIED if the user did not supply a function or INVALID_FUNCTION_SPECIFIED if the user provided an invalid function

get_error_message

Get the error message Input : the name of the function whose error message we should report Output: the function's error message or NO_FUNCTION_SPECIFIED if the user did not supply a function or INVALID_FUNCTION_SPECIFIED if the user provided an invalid function

get_error_msg

Get the error message

This function is identical to get_error_message

RETURN VALUES AND ERROR CODES

configure and set_parameter return 0 on success and 1 on error.

parameter_value returns the value on success and undef on error.

parameter_set_by returns an integer indicating who set the value and on error it returns BGPmon::Configure::SET_ERROR

In the event of an error, an error code and error message can be obtained using $code = get_error_code("function_name"); $msg = get_error_msg("function_name");

The following error codes are defined:

 0 - No Error
    'No Error';

 1 - No Function Specified in get_error_code/get_error_msg
    'Error reporting function called without specifying the function.';

 2 - Invalid Funtion in get_error_code/get_error_msg
    'Error reporting function called with invalid function name';

use constant NO_PARAMETER_SPECIFIED_CODE => 3; use constant NO_PARAMETER_SPECIFIED_MSG => 'No parameter name specified'; use constant NOT_A_VALID_PARAMETER_CODE => 4; use constant NOT_A_VALID_PARAMETER_MSG => 'Invalid parameter name'; use constant NO_VALUE_ASSIGNED_CODE => 5; use constant NO_VALUE_ASSIGNED_MSG => 'No value has been assigned to this parameter'; use constant UNDEFINED_SETBY_CODE => 6; use constant UNDEFINED_SETBY_MSG => 'The SetBy field of the parameter is undefined'; use constant INVALID_SETBY_CODE => 7; use constant INVALID_SETBY_MSG => 'The SetBy field of the parameter is invalid.'; use constant INVALID_VALUE_CODE => 8; use constant INVALID_VALUE_MSG => 'Invalid value for parameter'; use constant PARAMETER_CREATION_ERROR_CODE => 9; use constant PARAMETER_CREATION_ERROR_MSG => 'Error creating the paramter - missing parameter hash'; use constant PARAMETER_CREATION_MISSING_NAME_CODE => 10; use constant PARAMETER_CREATION_MISSING_NAME_MSG => 'Error creating the paramter - parameter name is missing'; use constant PARAMETER_CREATION_MISSING_TYPE_CODE => 11; use constant PARAMETER_CREATION_MISSING_TYPE_MSG => 'Error creating the paramter - parameter name is missing'; use constant PARAMETER_CREATION_INVALID_TYPE_CODE => 12; use constant PARAMETER_CREATION_INVALID_TYPE_MSG => 'Error creating the paramter - invalid type '; use constant PARAMETER_CREATION_INVALID_ELEMENT_CODE => 13; use constant PARAMETER_CREATION_INVALID_ELEMENT_MSG => 'Error creating the paramter - invalid element '; use constant PARAMETER_CREATION_INVALID_DEFAULT_CODE => 14; use constant PARAMETER_CREATION_INVALID_DEFAULT_MSG => 'Error creating the paramter - invalid default value '; use constant PARAMETER_CREATION_NO_H_OPT_CODE => 15; use constant PARAMETER_CREATION_NO_H_OPT_MSG => 'Error creating the paramter - parameter name -h and -help are reserved'; use constant PARAMETER_CREATION_INVALID_CONFIG_FILE_TYPE_CODE => 16; use constant PARAMETER_CREATION_INVALID_CONFIG_FILE_TYPE_MSG => 'Error creating the paramter - config file must be type FILE'; use constant COMMAND_LINE_USAGE_CONSTRUCTION_ERROR_CODE => 17; use constant COMMAND_LINE_USAGE_CONSTRUCTION_ERROR_MSG => 'Unable to construct usage message for command line'; use constant NO_CONFIG_FILE_SPECIFIED_CODE => 18; use constant NO_CONFIG_FILE_SPECIFIED_MSG => 'No configuration file specified'; use constant CONFIG_FILE_NOT_FOUND_CODE => 19; use constant CONFIG_FILE_NOT_FOUND_MSG => 'Configuration file not found'; use constant CONFIG_FILE_OPEN_FAILED_CODE => 20; use constant CONFIG_FILE_OPEN_FAILED_MSG => 'Failed to open configuration file'; use constant CONFIG_FILE_INVALID_LINE_CODE => 21; use constant CONFIG_FILE_INVALID_LINE_MSG => 'Invalid line in configuration file: ';

#1234567891123456789112345678911234567891123456789112345678911234567891123456789

AUTHOR ^

Dan Massey, <massey at cs.colostate.edu>

BUGS ^

Please report any bugs or feature requests to bgpmon@netsec.colostate.edu>.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc BGPmon::Configure

LICENSE AND COPYRIGHT ^

Copyright (c) 2012 Colorado State University

    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the "Software"), to deal in the Software without
    restriction, including without limitation the rights to use,
    copy, modify, merge, publish, distribute, sublicense, and/or
    sell copies of the Software, and to permit persons to whom
    the Software is furnished to do so, subject to the following
    conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    OTHER DEALINGS IN THE SOFTWARE.\

    File: Configure.pm

    Authors: Dan Massey
    Date: June 22, 2012
syntax highlighting: