libwhisker v2.0 ------------------------------------------------------------------------------ This text file describes all the various special values of the {'whisker'} anonymous hash. All values are for the request hash, unless otherwise noted. Request hashes are also called 'hin' hashes, and response hashes are 'hout'. ------------------------------------------------------------------------------ ==== Standard configuration ==== {'whisker'}->{'host'} - What host you want to connect to. Default is 'localhost'. {'whisker'}->{'port'} - Port to connect to for HTTP host (not proxy). Default is 80. {'whisker'}->{'proxy_host'} - The proxy host to use while attemping to make the HTTP request to the specified host. Note that libwhisker will go into proxy mode if proxy_host is defined, so be sure to delete it from the hash if you don't want to use a proxy. By default it is not defined. {'whisker'}->{'proxy_port'} - The port of the proxy server to connect to. {'whisker'}->{'method'} - The HTTP method to use. Default is 'GET'. {'whisker'}->{'uri'} - The actual URL desired. {'whisker'}->{'version'} - In the request (hin) hash, this tells libwhisker what HTTP version request to perform. Recognized values are '0.9', '1.0', and '1.1'. Default is '1.1'. In the result (hout) hash, this is the HTTP version response of the result. {'whisker'}->{'ssl'} - If set to 1, libwhisker will use SSL for the connection. Default is 0. {'whisker'}->{'error'} - Only applicable in result (hout) hash; this contains the error message if any errors occured (it's empty otherwise). {'whisker'}->{'data'} - In request (hin) hash, this is additional data to send to the server (for example, via POST or PUT). libwhisker will automatically calculate the 'Content-Length' header if you haven't already done so. In result (hout) hash, this is the HTML/data sent from the server. {'whisker'}->{'code'} - Only applicable in result (hout) hash; this tells you the HTTP response code of the result. {'whisker'}->{'http_message'} - Only applicable in result (hout) hash; this tells you the HTTP response message of the request. ==== Advanced configuration ==== {'whisker'}->{'bind_socket'} - If set to 1, libwhisker will bind() the socket using a specified source port and IP address. {'whisker'}->{'bind_port'} - Set to a numeric source port address. If this value is not defined, then a default port of 14011 is used. Note that it must be a valid port number (1-65535), and specifying a port less than 1024 may require root privileges. {'whisker'}->{'bind_addr'} - Set to the IP address you wish to bind the socket to (aka, to use a source IP). Note that on almost all systems, the socket has to be a valid local IP address--you just can't pick random IPs and expect libwhisker to spoof the packets for you. It doesn't quite work like that. If this value is not defined, then INADDR_ANY is used by default. Note that you can *NOT* set this to INADDR_ANY or any other TCP constant: it must be an address. {'whisker'}->{'ignore_duplicate_headers'} - If a server sends the same header (potentially with different values) twice, this will only save the result of the last header value. If set to 0, it will actually make an anonymous array under that header name in the hash, and push all the values into the array--this means you have to test every header result to see if it's an ARRAY REF (using ref() function) before you can use it. Default is 1 (ignore duplicates). {'whisker'}->{'normalize_incoming_headers'} - If set to 1, libwhisker will 'normalize' the header names in an attempt to be more standard. The normalization will make the first character, and any character after the '-' uppercase. So "Content-length" and "blah-blah-blah" will become "Content-Length" and "Blah-Blah-Blah". The 'lowercase_incoming_headers' option will override this option. The default value is 1. {'whisker'}->{'lowercase_incoming_headers'} - If set to 1, libwhisker will lowercase the names of all incoming headers before putting them into the header hash. The default is 0. {'whisker'}->{'timeout'} - This is the amount of time, in seconds, that libwhisker will wait for data from a webserver before aborting. The default is 10 (seconds). {'whisker'}->{'anti_ids'} - Tells http_do_request to use anti-IDS methods. This value specifies which methods to use. {'whisker'}->{'force_close'} - Tells libwhisker to close the socket, regardless of any persistant connection/keep-alives. {'whisker'}->{'trailing_slurp'} - Tells libwhisker how to handle funky persistent connection problems... namely, what to do with extra data waiting around *before* the request is sent. If set to 0 (default), the data is inserted into the incoming data queue and processed like anything else. If set to 1, it is instead appended to {'whisker'}->{'slurped'} and a NULL is added to the end. A value of 2 will discard the data. {'whisker'}->{'force_bodysnatch'} - This has nothing to do with aliens taking over the planet; it actually tells whisker that it should look for data after the headers. Use in the rare time where you want snag any data sent after a HEAD request (some servers/CGIs/ISAPI-handlers are broken in that they ignore HEAD and treat it as a GET). {'whisker'}->{'save_raw_headers'} - Causes libwhisker to save the raw request and header lines (it will parse them as well, but it lets you see the raw data that was parsed). The raw data is placed into {'whisker'}->{'raw_header_data'} of the output hash. ==== HTTP request specifics ==== (Note: for the specifics of how all these elements compose the HTTP request, check the LW::http_req2line function) {'whisker'}->{'http_space1'} - This value is placed between the method and uri in the HTTP request. Default is ' ', a single space. {'whisker'}->{'uri_prefix'} - This value is placed before the actual uri. The default value is empty. {'whisker'}->{'uri_user'} - An optional username to put into the uri (note: this is not related to the HTTP Authentication header). Default is empty. {'whisker'}->{'uri_password'} - An optional password to put into the uri (note: this is not related to the HTTP Authentication header). Default is empty. {'whisker'}->{'uri_postfix'} - This value is placed after the actual uri. The default value is empty. {'whisker'}->{'uri_param_sep'} - What to separate parameters with. Default is '?'. {'whisker'}->{'parameters'} - URL parameters. If not empty, then uri_param_sep will be placed between uri and uri_param. {'whisker'}->{'http_space2'} - This value is placed between the uri and HTTP version in the HTTP request. Default is ' ', a single space. {'whisker'}->{'http_eol'} - The terminating header line character. Defaults to '\r\n'. {'whisker'}->{'include_host_in_uri'} - If set to 1, this will include the host in the HTTP request, in the form of http://host:port/uri. This is typically needed for proxies. {'whisker'}->{'full_request_override'} - If this entry is not empty, this value will be sent instead of the constructed HTTP request line. {'whisker'}->{'raw_header_data'} - If this entry is not empty, it will be inserted into the HTTP request stream after the initial HTTP request and headers, but before the final blank line. This lets you specify arbitrary headers or other wackiness in the request. ==== SSL Stuff ==== {'whisker'}->{'ssl_rsacertfile'} - Request hash only; specify the client RSA private key file to send to the server. Only valid with Net::SSLeay. {'whisker'}->{'ssl_certfile'} - Request hash only; specify the client certificate file to send to the server. Only valid with Net::SSLeay. {'whisker'}->{'ssl_ciphers'} - Request hash only; list of valid ciphers to pass to the server. Only valid with Net::SSLeay. {'whisker'}->{'save_ssl_info'} - Request hash only; if set to 1, libwhisker will save various SSL connection parameters (see below). Only valid when using Net::SSLeay. {'whisker'}->{'ssl_cipher'} {'whisker'}->{'ssl_cert_subject'} {'whisker'}->{'ssl_cert_issuer'} - When save_ssl_info is set to 1, the negotiated cipher, as well as the server's certficate subject and issuer are saved in the response hash. ==== Miscellaneous ==== {'whisker'}->{'stats_reqs'} - Only applicable in result (hout) hash; this tells how many requests have been made to that host (total). {'whisker'}->{'stats_syns'} - Only applicable in result (hout) hash; this tells how many socket connections have been made to that host (total). {'whisker'}->{'INITIAL_MAGIC'} - This is a special value which tells whisker if the hash has been properly initialized, and what type of hash it is. A hash returned by LW::http_init_request will have a value of 31339. Hash results returned from LW::http_do_request(_ex) will set the output/response hash value to 31340. If you're constructing a request hash from scratch, you will need to set this value--however, make sure you also set/define the default hash values, as the library assumes these to exist. {'whisker'}->{'cookies'} - This is a special anonymous array, which is used by the cookie functions. You would not normally use it. Response hash (hout) only. {'whisker'}->{'header_order'} - Response hash only; this is the order the headers were received in. Note: this is an anonymous array. {'whisker'}->{'abnormal_header_spacing'} - Response hash only; indicates number of headers that were not in the format of Name: Value (as in, included something other than a single space between the Name: and Value) {'whisker'}->{'100_continue'} - Response hash only; indicates the number of 100 Continue responses received by libwhisker (which are ignored, since they are not the final answer) {'whisker'}->{'retry'} - The number of times to automatically retry failed connection attempts. This only applies to http_do_request(). Set to 0 to disable automatic retries. {'whisker'}->{'retry_errors'} - Response hash only; this is an anonymous array holding error messages received before the request was retried.