BGPmon::Configure - BGPmon Client Configuration
This module sets initial configuration variables from a combination of default values, configuration file parameters, and command line options.
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"; }
configure parameter_value parameter_set_by set_parameter
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
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
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
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 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 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 the error message
This function is identical to get_error_message
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
Dan Massey, <massey at cs.colostate.edu>
<massey at cs.colostate.edu>
Please report any bugs or feature requests to bgpmon@netsec.colostate.edu>.
bgpmon@netsec.colostate.edu>
You can find documentation for this module with the perldoc command.
perldoc BGPmon::Configure
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
To install BGPmon::Log, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BGPmon::Log
CPAN shell
perl -MCPAN -e shell install BGPmon::Log
For more information on module installation, please visit the detailed CPAN module installation guide.