{ Method=> 'GET', Url=> 'http://www.citap.be/', Qs_var=> [], Qs_fixed=> [], Exp=> "Consulting Internet Technology Alex Peeters", Exp_Fault=> ">>>NIHIL<<<", Msg=> "Consulting Internet Technology Alex Peeters", Msg_Fault=> "Consulting Internet Technology Alex Peeters", Perfdata_Label=> 'Perfdata Label 1'},
);
$objectWebTransact->check ( { } );
undef$objectWebTransact;
=head1 DESCRIPTION
This module implements a check of a Web Transaction.
A Web transaction is a sequence of web pages, often fill out forms, that accomplishes an enquiry or an update.
Common examples are database searches and registration activities.
A Web transaction is specified by
=over 4
=item * asnmtapInherited
A required reference to an ASNMTAP::Asnmtap::Plugins or ASNMTAP::Asnmtap::Plugins::Nagios subclass
Through this way of working we inherited the command line setting from the proxy.
When we specify at the command prompt I<--proxy=username;password@proxyserver:port|domain[,domain]>, the needed and required proxy settings are automatically set.
The command line options I<--timeout>, I<--debug> and I<--debugfile> are also inherited.
B<debug> writes the string form of the request (including query_string) and the response to STDERR.
I<_browseragent> is inherited and specifies the name that your application should usewhenit presents itself on the network.
I<_SSLversion> is inherited and specifies the SSL version to use.
=item * a list of URLs where eachURL is a page in the transaction
=item * corresponding Query Strings containing the CGI names and value pairs to post the page
=item * a means of determining from the content, whether a response is either OK or a failure (WARNING, CRITICAL or UNKNOWN).
=over 4
=item 'KeepAlive'and 'SSL session reuse'
Only SSLv3 and TLSv1 are supporting 'KeepAlive'and 'SSL session reuse'.
To make SSL session reuse possible, 'KeepAlive'need to be on 'On'.
Verify that your browseragent string on the destination servers don't have someting like a 'nokeepalive', 'downgrade-1.0' or 'force-response-1.0'.
Verify that the 'SSL Session Cache'on the destination servers are enabled.
=over 4
=item Apache
=over 4
=item httpd.conf
# KeepAlive: Whether or not to allow persistent connections (more than one request per connection).
KeepAlive On
# The following directives modify normal HTTP response behavior to handle known problems with browser implementations.
A new ASNMTAP::Asnmtap::Plugins::WebTransact object must be created withthe I<new> method.
A reference to array of hash references ( \@URLS) is required.
The field urls contains a reference to a list of (hashes) records representing the Web Transaction.
This is the constructor fora ASNMTAP::Asnmtap::Plugins::WebTransact->new object. C<ref_to_array_of_hash_refs> is a reference to an array of records (anon hash refs) in the format:-
Qs_fixed and Qs_var are used to generate a query string.
Exp, Exp_Fault and Exp_Return are normal Perl patterns without pattern match delimiters. Most often they are strings.
=over 4
=item Method
scalar, possible values: GET, HEAD or POST
=over 4
=item GET
The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unlessthat text happens to be the output of the process.
=item HEAD
The HEAD method is identical to GET except that the server MUST NOT returna message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used forobtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used fortesting hypertext links forvalidity, accessibility, and recent modification.
=item POST
The POST method is used to request that the origin server acceptthe entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.
B<Qs_var> contains placeholders forvaluesthat are not known untilrun time.
In both cases, the formatof these fields is a reference to an array containing alternating CGI
variable names and valueseg \(name1, v1, name2, v2, ...) produces a query string name1=v1&name2=v2&..
Qs_var allows valuesto be specified in three ways :-
=over 4
=item *
a string that will be used as a key in the hash of arguments passed to the check method.
=item *
a positive integer (0, 1, ...)
=back
In the latter case, the integer will be used as an indexof the array of matches found from the
lastset of patterns withmemory (specified by the Exp field). So [ cgi_var_name=> 0 ] leads to
a query string cgi_var_name = <the_first_match_in_the_set_of_Exp_patterns>
=over 4
=item *
an array refof the form [ match_index=> code_ref ]
In this case, the subroutine referred to by coderef is a subroutine withone parameter and it will be called withthat parameter set to the first element in the array (the indexof a former match). One may choose to dothis withvery dynamic web systems such as the SAP R3 module forIIS in which the CGI names and valuesmay need to be dragged out of former responses.
If 'CmrDetailPat'is used as an Exp field, then a subsequent GET or POST can make useof
Qs_var values'AddStars_to_Name'and 'DelStars_from_Name'to either append some asterisks to the value of the
web form name addr1_data-name1[1] or remove the stars.
=back
In this case, the subroutine referred to by coderef is a subroutine withone parameter and it will be
called withthat parameter set to the first element in the array (the indexof a former match).
One may choose to dothis withvery dynamic web systems such as the SAP R3 module forIIS in which the
CGI names and valuesmay need to be dragged out of former responses.
Is an array reference containing the name value pairs of any parameters whose value is known only at run time.
The formatis [ cgi_parm_name=> val_at_run_time, ... ] where cgi_parm_name is the name of a fill out form parameter and val_at_run_time is a string used as a key to get the value of the cgi parameter.
Qs_var = [ form_name_1=> 0, form_name_2=> 1 ..] will lead to a query_string like
form_name_1 = $matches[0], form_name_2 = $matches[1] ... in $self->_make_req() by
@matches= $self->matches() and using 0, 1 etc as indices of @matches.
=item Qs_fixed
B<Qs_fixed> contains the name value pairs that are known at compile timewhereas.
Is an array reference containing name value pairs.
The formatis [ cgi_var_name=> val, ... ] where cgi_var_name is the name of a fill out form parameter and val is a string withthe value of the cgi parameter
=item Exp .
B<Exp> is the pattern that whenmatched against the respose to the URL (in the same hash) indicates success.
Is an scalar(value is a string) or an array
$objectWebTransact->matches() will updated withthe set of matches it finds by matching
patterns withmemory (ie patterns in paren) from the Exp field against the request response.
=item Exp_Fault
B<Exp_Fault> is the pattern that indicates the response is a failure.
If these patterns contain parentheses eg 'match a lot (.*)', then the match is saved foruseby
Qs_var. Note that there should be only B<one> pattern per element of the Exp list. Nested patterns
( C<yada(blah(.+)blurble(x|y|zz(top.*))> ) will not work as expected.
Is an scalar(value is a string), ex. blurb
=item Exp_Return
B<Exp_Return> is the pattern that indicates the response is a return.
Is an hash, { var_label_1=> EXP_VAR_LABEL_1, ... }
=item Msg .
This message is added to the error field whennot all Exp found.
Is an scalar(value is a string), ex. 'Status error when not all Exp found'
=item Msg_Fault
This message is added to the error field whenExp_Fault found.
Is an scalar(value is a string), ex. 'Status error when Exp_Fault found'
=item Timeout
This means that forthis URL the specified timeout will be used.
Is an scalar(value is a integer greater then 0), ex. 30
=item Perfdata_Label
This means that forthis URL there performance data will be created and the name forthe label equals the value from Perfdata_Label.
The first timewe call $objectWebTransact->check ( { }, ... ),
is an scalar, value is 0, 1 or undef(default)
undef: current (browser) session will be used, but at the first
all a new (browser) session will automaticallybe created
0 : current (browser) session will be used
1 : new (browser) session will be created
This means that whenyou specify newAgent=> 0 the first timeyou call $objectWebTransact->check, it will be treated as newAgent=> 1, to ensure that an (browser) session is created.
Every timewhel fora following call $objectWebTransact->check ( { }, ... ), newAgent equals 1, then a new (browser) session is created.
When newAgent equals 0, then we using the same (browser) session again.
is an scalar, value greater then 0 or undef(default)
When timeout equals undef, then we using the timeout from the parent object.
Optional, is an scalar, value is greater the 0
=item I<triesTiming>
Every timewe call $objectWebTransact->check ( { }, triesTiming=> '1,3,15', ... ), to get a web page and run into a possibly-temporary error (like a DNS lookup timeout), it'll waita few seconds and retry a few times.
is an string that controls how many timesit should retry, and how long the pauses should be, valuesgreater then 0 separated by a ','or undef(default)
When triesTiming equals undefor an empty-string, this means not to retry at all.
If you specify a string withseveral numbers in it (like '1,3,15'), then that means WebTransact can retry as that many times(i.e., one initial try, plus a maximum of the three retries, because three numbers there), and that it should waitfirst those numbers of seconds eachtime.
So triesTiming=> '1,3,15'basically means:
trythe request; returnit unlessit's a temporary-looking error;
sleep1;
retry the request; returnit unlessit's a temporary-looking error;
sleep3;
retry the request; returnit unlessit's a temporary-looking error;
sleep15;
retry the request; returnit;
=item I<triesCodes>
Is an string of HTTP codes that merit a retry (like 500 and 408, but unlike 404 or 200), valuesgreater then 200 separated by a ','or '408,500,502,503,504'(default).
408 Request Timeout: The client did not senda request within the required timeperiod
500 Can't connect to ..., Connect failed, Proxy connect failed, Server Error, SSL negotiation failed, SSL read timeout or Internal Server Error: The server had some sort of internal error trying to fulfil the request. The client may see a partial page or error message. It's a fault in the server and happens all too frequently.
502 Bad Gateway: Bad Gateway: a server being used by this Web server hassent an invalid response. The response by an intermediary server was invalid. This may happen ifthere is a problem withthe DNS routing tables.
503 Service Unavailable: Service temporarily unavailable because of currently/temporary overload or maintenance.
504 Gateway Timeout: The server did not respond back to the gateway within acceptable timeperiod
=item I<openAppend>
Is an scalar, opendebugfile as 'Writes, Appends, and Creates'mode when1, otherwise opendebugfile in 'Creates, Writes, and Truncates'mode.
=item I<cookies>
Is an scalar, value is 0 or 1 (default)
=item I<protocol>
0 = defaultand 1 = force 'HTTP/1.1'
Is an scalar, value is 0 or 1 (default)
=item I<keepAlive>
0 = defaultand 1 = 'Keep-Alive'
Is an scalar, value is 0 or 1 (default)
=item I<download_images>
get the images found by HTML::LinkExtor in the page, provided those images have not already been ed.
Is an scalar, value is 0 (default) or 1
=item I<fail_if_1>
B<fail_if_1> ifset (the default) causes the check to fail whenthe first
web page fails. Clearing this flag is useful ifyou want to get a bunch of