Next Previous Contents

5. Playing Back Sessions with WebClient

WebClient is an HTTP submitter that simulates the network behavior of a web browser (or other HTTP client). It can be used to measure the performance of a web server. In normal operation, WebClient will read a session's worth of URL's from a file, submit these to a webserver host, and time the responses. Statistics are computed an shown for one or more repeated session runs.

5.1 Features

WebClient provides the following features and functions:

5.2 Command Line Summary

By typing webclient -h or webclient --help at the command line, a summary of command line options will be printed, as shown below. More detailed documentation for each of these flags is presented in the section Webclient Command Line Flags below.


Usage: webclient [options] 

-A, --alarm=<time>       turns on timeout alarms (delay 'time')
-c, --cache-emulation    turns on the gif cache emulation (requires -g flag)
-d, --debug              print basic debugging messages 
-D, --Debug              turns on verbose debugging
-E, --Debug-debug        turns on extra verbose debugging
-e, --print-each         print individual response time observations
-f, --input-file=<file>  specifies the url list file to be run
-g, --fetch-gifs         turns on fetching of gif files
-h, --help               print this message
-i, --ignore-checksums   don't validate web pages with checksums
-L, --log-file=<file>    specify name of error log file
-m, --shmem=<child:shmkey> defines common shared memory segment
-P, --proxy=<proxy:port> specifies the proxyserver and port
-q, --debug-time         turns on debugging output for timing statistics
-Q, --Debug-time         turns on verbose timing debug output
-R, --random-seed=<seed> specify seed used to generate random think times
-r, --report-file=<file> specifies the report file name
-t, --trace-file=<file> write HTTP traces to file
-u, --user-pin-pw=<username:userpin:userpasswd> same as specifying 
        --substitute=<<USER>>:username 
        --substitute=<<PIN>>:userpin 
        --substitute=<<PASS>>:userpasswd 

-U, --user-agent=<string> specify value of 'User-Agent:' in HTTP header
        string must be enclosed in single quotes if it contains [{( etc...
-v, --new-url-file=<file>     recalculate checksums, write new input file
-W, --wait-interval=<seconds> pause after each trial, before starting next
-w, --webserver=<server:port> specifies the webserver and port
-x, --timestamps              write request start and end timestamps

Flags without short-form equivalents:
--access-log=<file>           write webserver-style access log
--clean-exit=<file>           specifies urls to run on error or interrupt
--cookie-path=<URL>           make sure that cookie was set for path
--fork                        run in the background after validating args
--handle=<field>              replace handle values in header from returned page data
--header-add=<field:val>      substitute or add field-value to HTTP header
--header-file=<file>          use the HTTP header found in this file
--header-subst=<field:val>    substitute field-value to HTTP header
--http-version=<float>        use HTTP/1.0 or 1.1 protocol
--no-bug-compat               enable strict conformance to HTTP standard
--no-keep-alive               do not use keep-alive sockets to feth gifs
--num-threads=<int>           number of threads to use for gif fetching
--num-sessions=<int>          override number of times to replay session
--quiet                       minimize messages written to stdout
--skip-stats                  don't collect or print performance statistics
--show-progress               write out each URL as its fetched
--substitute=<key:value>      replace "key" with "value" in POST or URL
--think-time=<float>          override the think time in the input file
--think-fixed                 think time specifies a fixed time interval
--think-exponential           think time is random exponential distribution
--think-gaussian              think time is random gaussian distribution
--version                     print version info and exit
--warn-checksums              print warnings when page checksums are bad
SSL options:

      --ssl-server           use SSL to connect to server
  -S, --server-cipher=NUM    force use of a specific cipher
      --server-timeout=NUM   set SSL session cache timeout (seconds)
      --ssl-browser          use SSL to connect to browser
      --browser-cipher=NUM   force use of a specific cipher
      --browser-timeout=NUM  set SSL session cache timeout (seconds)
      --certif=<filename>    specify file containing certificates
  -k, --keyring=<filename>   specify file containing keys
  -K, --password=<passwd>    specify keyring password
  -N, --distinguish=<name>   specify a distinguished name

Cipher suites may be specified in the form SSLV2:N with N 1,2,3,..7
or SSLV3:NN for NN=00, 01, 02 ... 06 or 0A.If a cipher suite has been 
specified, then no cipher suite negotiation is performed. 


5.3 Example Usage

The shell script run.webclient in the examples directory provides a brief introduction to the most commonly used options. It is reproduced below:


#!/bin/sh
#
# run.webclient
#
# This is a simple script that makes it easier to run the "webclient"
# tool.  You should modify this script to suit your installation,
# tastes and style.
#
# To run this script, simply say "run.webclient"
#
#----------------------------------------------------------
# set the environment so that the actual binaries can be found
export PATH=$PATH:../bin
export LIBPATH=$LIBPATH:../lib
#
#----------------------------------------------------------
# Flags:
# -A 10: log an alarm if the server doesn't respond within 10 seconds
#
# -i: ignore checksum errors when comparing checksums recorded in the
#     input file to the checksums of the returned web pages.  This is
#     useful when the web page has a date embedded in it, and the date
#     has changed since the input file has been created.
#
# -f webclient.input: specify the input file containing the URL's to test
#
# -w webbank.com:8080:  use the web server on webbank.com, port 8080
#
# -r webclient.report: write a report to the file "webclient.report"
#
# -t webclient.trace: write a trace of all data exchanged with the 
#    webserver to the file "webclient.trace".
#
# webclient -A 10 -i \
#       -f webclient.input \
#       -w webank.com:8080 \
#       -r webclient.report \
#       -t webclient.trace
#
#----------------------------------------------------------
# Same as above, except that SSL encryption should be used on the 
# connection 
#
# --ssl-server:      Negotiate the SSL cipher to use
#                    Note the double-dash: this is a "long-form" option.
#                    Not all long-form options have single-letter equivalents;
#                    there are not enough letters in the alphabet.
#
# webclient -A 10 -i \
#       -f webclient.input \
#       --ssl-server \
#       -w webank.com:443 \
#       -r webclient.ssl.report \
#       -t webclient.trace
#
#----------------------------------------------------------
# Same as above, but the client is told to claim that it is a browser
# of a particular variety (in this case, Netscape version 4 for AIX, 
# with an english-language defaults.).  
#
# webclient -A 10 -i \
#       -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)' \
#       -f webclient.input \
#       --ssl-server \
#       -w webank.com:443 \
#       -r webclient.ssl.report \
#       -t webclient.trace
#
# Some other User-Agent strings:
# -U 'Mozilla/3.0 (Win95; I)'     Netscape Version 3 for Windows 95
# -U 'Mozilla/3.04 (Win95; U)'    Netscape Version 3 for Windows 95
# -U 'Mozilla/2.02 (OS/2; U)'     Netscape Version 2 for OS/2
# -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)'           NS for AIX
# -U 'Mozilla/4.05 [en] (X11; U; Linux 2.0.32 i586)'      NS for Linux
#
# Note that Internet Explorer tries hard to be compatible in every way: 
# -U 'Mozilla/4.0 (compatible; MSIE 4.01; Windows 95)'    MSIE for W95
#
# Mozilla is not the only possible User-Agent name:
# -U 'Konqueror/1.0'             KDE File Manager desktop client
# -U 'Lynx/2.7.1 libwww-FM/2.14' Lynx command line browser
#
#----------------------------------------------------------
# As above, except that the host to be accessed lies on the far side
# of a proxy bastion firewall.  
#
# -P proxy.server.com:80  The proxy server listens on port 80
#
# webclient -A 10 -i \
#       -P proxy.server.com \
#       -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)' \
#       -f webclient.input \
#       --ssl-server \
#       -w webank.com:443 \
#       -r webclient.ssl.report \
#       -t webclient.trace
#
#----------------------------------------------------------
# As above, except that the the URL's in "cleanup.input" will be sent to
# the webserver if webclient is interrupted (with a control-C, or with
# a "kill -USR1 <pid-of-webclient>", or if webclient detects an error
# (such as a URL that is not found, a bad checksum, or other HTTP problem).
# The goal of cleanup is to log the user out gracefully if/when an error
# occurs.
#
# -P proxy.server.com:80  The proxy server listens on port 80
#
# webclient -A 10 -i \
#       -P proxy.server.com \
#       -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)' \
#       -f webclient.input \
#       --ssl-server \
#       -w webank.com:443 \
#       --clean-exit=cleanup.input \
#       -r webclient.ssl.report \
#       -t webclient.trace
#
#----------------------------------------------------------
#
# Putting it all together:
# the command below should allow a connection to be made to a real-life
# server on the net.  To get past the home page, you will need a real-life
# account and password, but the below should at least get to the home page.
#
webclient -A 120 -i \
        -P proxy.asdf.com:80 \
        -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)' \
        -f nb.client.input \
        --ssl-server \
        --clean-exit=cleanup.input \
        -w server.nationonline.com:443 \
        -r nb.ssl.report -t nb.trace
#
#
#----------------------------------------------------------
#----------------------------------------------------------
#----------------------------------------------------------
# Some further flags & examples:
#
# -S SSLV3:04:       Use SSLV3 encoding standard 04 (128-bit RC5)
#
# -k mykeydb.kdb:    use the keyring 'mykeydb.kdb'.  
#
# -K linas:          the password to the keyring file is 'linas' 
#
# -b mykeystash.sth: instead of specifying a password, a password stash 
#                    file can be used instead.
#
#----------------------------------------------------------
# As above, except that the SOCKS-ified version of webclient is used.  
# The socks-ified version is able to reach external hosts from
# behind a SOCKS-style firewall.  Note that SOCKS must be correctly
# configured on your host machine.  Use SOCKS only if you do not have
# a proxy server, or cannot get access to a NAT/Masquerading firewall.
#
# export SOCKS_SERVER=socksy.lady.com
export SOCKS_SERVER=socks.hosiery.com
#
# rwebclient -A 10 -i \
#       -U 'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)' \
#       -f webclient.input \
#       -S SSLV3:04 -k mykeydb.kdb -K linas \
#       -w webank.com:443 \
#       -r webclient.ssl.report -t webclient.trace
#
#----------------------------------------------------------
#----------------------------------------------------------
#----------------------------------------------------------

5.4 Example Input Files

Webclient supports two styles of input files: 'oldstyle' and 'newstyle'. The new format was chosen to allow for greater flexibility. The old format is supported for backwards compatibility. More detailed documentation for the input file formats is provided in the section Webclient Input File Format below.

The following is an example of the old file format:


# this is an example comment
# a session must start with a <<START>> delimiter
<<START>>
#
# the HTTP method is followed by a run count and checksum information
GET /logon 1.00 983210 324602 152 110 491
GET /logon/validate.js -1.00 11358531 4156403 1740 286 117
#
# data for the body of a post appears on the same line, before the run count.
POST /proclogin.ns UserID=<<USER>>&Pin=<<PIN>>&Password=<<PASS>>&PageGood=%2Fbank%2Finit.html&PageBad=%2Flogon%2Flogon.html%3FStatus_Code%3Dlogon_error&ProductName=Netscape&ReleaseVersion=4.04+%5Ben%5D&ClientOS=X11&CountryCode=USA&Language=ENU&x=25&y=9 1.00 1439849 597641 193 184 286
GET /bank/history.html?phase=SHOW_FORM&account_index=5 1.00 1910842 913002 228 216 541
POST /bank/history.html transaction_type=++1&transaction_source=&transaction_period=&start_date=&end_date=&low_amount=&high_amount=&low_check_number=&high_check_number=&maximum_number_of_transactions=99&enter.x=45&enter.y=19 1.00 2106710 969606 260 248 541
GET /bank/acctxdet.html?account_index=5&reference_number=119115157977 1.00 1506792 691736 186 174 541
GET /bank/history.html 1.00 2106710 969606 260 248 541
POST /bank/history.html done.x=47&done.y=5 1.00 1439832 597624 193 184 286
GET /proclogoff.ns 1.00 276785 105313 38 23 621
#
# note that fully qualified URL's can be used as well:
GET http://bank.com/homepage.html 1.00 456982 10188 42 73 12
#
# The end of the session is delimited by <<END>> followed
# by the playback count (5) and the think time (12.0 seconds)
<<END>> 5 12.0

An example of a new style input file follows below. Note that the mark-up is much more verbose and is much more XML-like.


# this is an example comment
# a session must start with a <<START>> delimiter
<<START>>
#
# The details of a request are broken out into multiple lines
<<REQUEST>> GET /logon 
<<COUNT>> 1.00 
<<CKSUM>> 983210 324602 152 110 491
<<REQUEST>> GET /logon/validate.js 
<<COUNT>> -1.00 
<<CKSUM>>11358531 4156403 1740 286 117
#
# <<MARK>> means that summary statistics should be generated 
# for both of the above URL's taken together as one.
<<MARK>>
#
# <<THINK>> implies that this is where the client should pause to think.
<<THINK>>
#
<<REQUEST>>POST /proclogin.ns 
# The body of the post occurs between BODY tags
<<BODY>>
UserID=<<USER>>&Pin=<<PIN>>&Password=<<PASS>>&PageGood=%2Fbank%2Finit.html&PageBad=%2Flogon%2Flogon.html%3FStatus_Code%3Dlogon_error&ProductName=Netscape&ReleaseVersion=4.04+%5Ben%5D&ClientOS=X11&CountryCode=USA&Language=ENU&x=25&y=9 
<</BODY>>
<<COUNT>> 1.00 
<<CKSUM>> 1439849 597641 193 184 286
<<MARK>>
<<THINK>>
#
<<REQUEST>>GET /bank/history.html?phase=SHOW_FORM&account_index=5
<<COUNT>> 1.00
<<CKSUM>> 1910842 913002 228 216 541
<<REQUEST>> POST /bank/history.html 
<<BODY>>
transaction_type=++1&transaction_source=&transaction_period=&start_date=&end_date=&low_amount=&high_amount=&low_check_number=&high_check_number=&maximum_number_of_transactions=99&enter.x=45&enter.y=19
<</BODY>>
<<COUNT>> 1.00
<<CKSUM>> 2106710 969606 260 248 541
<<MARK>>
<<THINK>>

<<REQUEST>> GET /bank/acctxdet.html?account_index=5&reference_number=119115157977 
<<COUNT>> 1.00 
<<CKSUM>> 1506792 691736 186 174 541
<<MARK>>
<<THINK>>

<<REQUEST>> GET /bank/history.html 
<<COUNT>> 1.00
<<CKSUM>> 2106710 969606 260 248 541
<<MARK>>
# for this interval only, the think time will be 45 seconds
<<THINK>> 45.0

<<REQUEST>> POST /bank/history.html 
<<BODY>>
done.x=47&done.y=5
<</BODY>>
<<COUNT>> 1.00
<<CKSUM>> 1439832 597624 193 184 286
<<MARK>>
<<THINK>>

<<REQUEST>> GET /proclogoff.ns
<<COUNT>> 1.00
<<CKSUM>> 276785 105313 38 23 621
<<MARK>>
<<THINK>>
#
# The end of the session is delimited by <<END>> followed
# by the playback count (5) and the think time (12.0 seconds)
<<END>> 5 12.0


Next Previous Contents