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.