define(MC_TITLE,webclient)
define(MC_DATE,98/05/14)
include(mc_html_head.h)
<!-- @(#) webclient.in 1.4@(#) -->
</UL><FONT SIZE=+1><STRONG>NAME</STRONG></FONT><UL>
webclient - WebStone benchmark load-generating program
</UL><FONT SIZE=+1><STRONG>SYNOPSIS</STRONG></FONT><UL>
<STRONG>webclient</STRONG>
-w webserver
-n numclients
[ -t run_time | -l loop_count ]
[ -dsvRT ]
[ -c webmasterhost:port ]
[ -u URL_file | URL [...] ]
[ -D debugfile ]
[ -P proxyserver ]
[ -S seed ]
[ -p port_num ]
</UL><FONT SIZE=+1><STRONG>DESCRIPTION</STRONG></FONT><UL>
<P>
<STRONG>webclient</STRONG>
is the program that makes requests of the target Web server and
records timing data to represent the Web server's performance.
It creates multiple instances of itself (either threads or processes)
according to the "-n" command line option.  Each instance then makes
requests of the Web server, according to the list of load URLs that
was provided.  As the results of each request are received
<STRONG>webclient</STRONG>
records the amount of data received and the elapsed time.  At the
end of the test run
<STRONG>webclient</STRONG>
writes a results summary to its standard output stream.
</UL><FONT SIZE=+1><STRONG>OPTIONS</STRONG></FONT><UL>
<DL>
<P><DT><STRONG>-D debugfile</STRONG>
<DD>Send debug data to this file on the client system.  Default: stderr.
<P><DT><STRONG>-P proxy_server</STRONG>
<DD>Generate the HTTP load by sending requests to this proxy server.
<P><DT><STRONG>-R</STRONG>
<DD>Record all transactions to a disk file.
<P><DT><STRONG>-S seed</STRONG>
<DD>Use the seed provided to initialize the random number generator that
chooses which page to request.
<P><DT><STRONG>-T</STRONG>
<DD>Turn on trace statements.
<P><DT><STRONG>-c webmasterhost:port</STRONG>
<DD>Connect to this port on the webmaster system to exchange control messages
and to report results.
<P><DT><STRONG>-d</STRONG>
<DD>Turn on debug and trace statements.
<P><DT><STRONG>-l loop_count</STRONG>
<DD>Cycle through the filelist "l" times, requesting each URL from the
server in turn.  Conflicts with "-t".
<P><DT><STRONG>-p portnum</STRONG>
<DD>Port number on which the Web server runs.  Default: 80.
<P><DT><STRONG>-s</STRONG>
<DD>Save all data retrieved from the Web server.
<P><DT><STRONG>-t run_time</STRONG>
<DD>Duration of the test, in minutes.  Conflicts with "-l".
<P><DT><STRONG>-u URL_file</STRONG>
<DD>Take load-generating URLs and weights from \fIURL_file\fR on the client system.
<P><DT><STRONG>-v</STRONG>
<DD>Enable verbose mode.
<P><DT><STRONG>-w webserver</STRONG>
<DD>Host name of the Web server to test.
</DL>
<P>
</UL><FONT SIZE=+1><STRONG>DETAILS</STRONG></FONT><UL>
<BR><FONT SIZE=+1><STRONG>Command Line</STRONG></FONT>
<P>
Either the "-t run_time" or the "-l loop_count" option must be given.
<P>
The list of URLs to be used to generate load must be specified in exactly
one of three ways: with the "-u URL_file" option, by giving the URLs
as command line arguments, or by providing the list of URLs and weights
on the standard input stream in the same format used for a URL file
(see </STRONG>FILES</STRONG>, below).
The sum of the weights in the URL list must not exceed the value
of RAND_MAX (from <unistd.h>) on the client system.
<P>
The "-S seed" option uses a known seed value to start the random number
generator that chooses which page to request.  The default is to use the
process ID number.  Using the same seed gives better consistency from
run to run.
<P>
All the file names that are settable on the command line refer to files
on the system on which
<STRONG>webclient</STRONG>
is running.
<P>
The "-c webmasterhost:port" option tells the
<STRONG>webclient</STRONG>
process how to connect to a
<STRONG>webmaster</STRONG>
process.  This option is not necessary if
<STRONG>webclient</STRONG>
is to run as a standalone process, not controlled by
<STRONG>webmaster</STRONG>.
<P><FONT SIZE=+1><STRONG>Execution</STRONG></FONT>
<P>
After setting up its run parameters, a
<STRONG>webclient</STRONG>
process creates the number of instances of itself that is specified
by the "-n numclients" parameter.  These instances may be processes
or threads; they're all called "processes" in this document.
<P>
The basic action for each
<STRONG>webclient</STRONG>
process is to issue an HTTP request and to measure the
length of time it takes for the request to be fulfilled.  As soon
as the request is fulfilled and the time is saved,
<STRONG>webclient</STRONG>
makes another request.
<P>
When the test run completes,
<STRONG>webclient</STRONG>
reports its results.  If the program is running standalone the
it writes the results summary to stdout.  If the program is under
the control of
<STRONG>webmaster</STRONG>
it waits until it's polled, then writes its results to the master socket.
<P><FONT SIZE=+1><STRONG>Test Load</STRONG></FONT>
<P>
If the run duration is specified with the "-l loop_count" option,
each
<STRONG>webclient</STRONG>
process requests the files in the URL list in order, traversing the
list
.I loop_count
times.
<P>
For a timed run ("-t run_time" option), the
<STRONG>webclient</STRONG>
processes use the weights from the URL list to decide how often
to request each URL from the server.
A pseudorandom number generator (\fIsrand()\fR) is used to choose which
URL to request.  A larger value for the URL's weight means that it is to
be requested more often.
If a URL is given on the command line or if no weight is entered
on the URL's line in the list, the URL is assigned a weight of 1.
<P>
A URL in the list may be a full URL that contains the protocol
(always "http://"), the server name, an optional port number, and the
file name.  Alternatively it may contain just the file name with a
leading slash ('/').
If no server name is given in the URL the Web
server name from the command line is used.
If no port number is given in the URL the value of "portnum" (the "-p
portnum" option or the default value) is used.
<P>
If a proxy server is to be tested, each URL in the URL list must
specify a server name.
</UL><FONT SIZE=+1><STRONG>FILES</STRONG></FONT><UL>
<STRONG>webclient</STRONG>
writes its output to its standard output stream.
<P>
Debug and trace output goes to the standard error stream by default.
<P>
If the "-R" command line flag is given, transaction information is
written to a local file whose name is generated by appending the
process ID to the string "logfile".
<P>
If the "-s" command line flag is given, all data from the Web server is
written to a local file whose name is generated by appending the
process ID to the string "savefile".
<P>
Other files used by
<STRONG>webclient</STRONG>
are specified on the command line.
If no URL files are specified on the command line,
<STRONG>webmaster</STRONG>
tries to read the list of URLs from its standard input stream.
<P>
During a test run
<STRONG>webmaster</STRONG>
keeps a socket open to each
<STRONG>webclient</STRONG>
process.  Make sure that the number of file descriptors available
to
<STRONG>webmaster</STRONG>
is greater than the total number of
<STRONG>webclient</STRONG>
processes to be run.
The "-R" and "-s" flags also each cause one file per
<STRONG>webclient</STRONG>
process to be opened.
<P>
<STRONG>File format for load URL lists:</STRONG>
<P>
For each URL to be used to generate the test load, the URL list
has an entry with the following form.  Comments and blank lines in
the list are ignored.  Each comment starts with a hash character ('#')
and continues to the end of the line.
<UL>
<P>
<TT>
&lt;URL&gt; &lt;weight&gt; [#&lt;comment&gt;]
</TT>
</UL>
</UL><FONT SIZE=+1><STRONG>ENVIRONMENT</STRONG></FONT><UL>
<STRONG>webmaster</STRONG>
does not use any environment variables.
</UL><FONT SIZE=+1><STRONG>AUTHOR</STRONG></FONT><UL>
include(copyright.h)
</UL><FONT SIZE=+1><STRONG>LIMITATIONS</STRONG></FONT><UL>
<P>
The command line options are too complicated.
<P>
It should not be an error to omit "-w webserver" from the command line
if all URLs in the URL list contain server names.
<P>
When a proxy server is being tested, 
<STRONG>webclient</STRONG>
should prepend the name of the Web server from the "-w servername"
option if there is no server name in the URL from the URL list.
</UL><FONT SIZE=+1><STRONG>SEE ALSO</STRONG></FONT><UL>
<A href=runbench.html>runbench(1)</A>,
<A href=webmaster.html>webmaster(1)</A>,
<A href=webstone.html>webstone(1)</A>,
<A href=webstonegui.html>webstonegui(1)<A>
include(mc_html_foot.h)
