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' 3 - There wasn't a name specified in get_error_code/get_error_msg. 'No parameter name specified' 4 - Input was not a valid parameter coe in get_error_code/get_error_msg. 'Invalid parameter name' 5 - No value has been assigned to the paramter. 'No value has been assigned to this parameter' 6 - The parameter must be given a Set By command but wasn't. 'The SetBy field of the parameter is undefined' 7 - Invalid SetBy field was given. 'The SetBy field of the parameter is invalid.' 8 - An invalid value was given for a parameter. 'Invalid value for parameter' 9 - There were no parameters to create. 'Error creating the paramter - missing parameter hash'; 10 - The parameter is missing a name. 'Error creating the paramter - parameter name is missing' 11 - The parameter is missing a type. 'Error creating the paramter - parameter name is missing' 12 - The parameter was given an invalid type. 'Error creating the paramter - invalid type ' 13 - The parameter was given an invalid or unsupported element in the hash. 'Error creating the paramter - invalid element ' 14 - The default attribute given for a parameter is invalid. 'Error creating the paramter - invalid default value ' 15 - The name of the parameter is a reserved name and cannot be used. 'Error creating the paramter - parameter name -h and -help are reserved' 16 - The configuration file could not be opened. 'Error creating the paramter - config file must be type FILE' 17 - Parameter wasn't given an GetOpt command. 'Unable to construct usage message for command line' 19 - The configuration file could not be found. 'Configuration file not found' 20 - Failed to open the configuration file. 'Failed to open configuration file'; 21 - There was in invalid line in the configuration file. 'Invalid line in configuration file: ';
M.Lawrence Weikum, <mweikum at rams.colostate.edu> Dan Massey, <massey at cs.colostate.edu>
<mweikum at rams.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: M. Lawrence Weikum, Dan Massey Date: 13 October 2013
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.