PolyDocs: Server Options
Web Polygraph

Polysrv documentation has been synchronized with Poly 2.1.0

usage: polysrv [--option] ...
options:
help list of options
version package version info
host_type package build environment information
verb_lvl <int> console verbosity level
dump <list> dump request/replies/errors headers/bodies to console
prn_reqs <bool> dump request headers to console
prn_reps <bool> dump reply headers to console
prn_errs <bool> dump detailed message info for every xaction error
notify <addr> send notifications to a [remote] monitoring program
label <str> run label
fd_limit <int> decrease default fd limit
config <file> configuration file name
cfg_dirs <list> directories to search for cfg files
console <file> redirect console output
log <file> detailed binary log file
log_size <size> binary log size limit
stats_cycle <time>statistics cycle length
linger_tout <time>linger on socket close
nagle <bool> use Nagle alg
xact_think <time>pause on xaction start
pconn_use_lmt <int>number of requests on a single connection
goal <int> total completions
file_scan <poll|select> system call to use for scanning ready files
fake_hosts <list> use given addresses, do not lookup real interfaces
idle_tout <list> exit after inactivity timeout
rng_seed <int> general purpose seed
unique_world <bool> use URL set that is unique across runs
port <int> listen port number
accept_lmt <int> accept no more at once
rep_sz <size> mean reply cont. length
track_rports <bool> track remote port [re]use
rport_wait_min <time> min a remote port should be in TIME_WAIT
obj_bday <TimeDistr> object creation time (-rel or +abs)
obj_life_cycle <TimeDistr> how often an object gets modified
obj_life_cycle_var <%> how variable obj mod times are
obj_with_lmt <%> ratio of objects with Last-Modified: header
obj_expire <ObjExp> various object expiration models

Name:--verb_lvl
Type:integer
Default:0

Verb_lvl specifies how much info will be printed to the console. Normally, level zero will have only a couple of lines per run. Level one will allow for interval and phase stats to be printed. A negative level will disable any output.

Most errors are reported with level zero.

Regardless of verb_lvl setting, all console messages are duplicated in the log.

Name:--dump
Type:list of strings
Default:no default
Version:2.2.0 and up

The --dump option controls what messages and what parts of messages should be printed on the console. Possible message types are: req[uest], rep[ly], and err[or]. Possible message parts are hdr (for ``header'') and body. Dumping of message bodies is not supported at the time of writing.

For example, to dump all request headers, one may use:

polysrv --dump req-hdr
To dump the headers of all requests and the headers of erroneous messages, use:
polyclt --dump req-hdr,err-hdr
Finally, to dump everything about errors, consider:
polyclt --dump err

and to dump all headers, use:
polyclt --dump hdr

Note that sometimes Polygraph does not have the required data at the time of dump. Polygraph will try to at least provide some meta information about the message then.

If a message part matches both negative (error) and positive (reply or request) type masks, the part may be printed twice.

This option obsoletes --prn_reqs, --prn_reps and --prn_errs options.

Name:--prn_reqs
Type:boolean
Default:no

When prn_reqs is set, Poly will print the request line and HTTP headers of each request. The requests are dumped to standard output.

Note that the output will not be logged.

This mode is very useful both for debugging benchmarking setup and for understanding Poly traffic model.

Name:--prn_reps
Type:boolean
Default:no

When prn_reps is set, Poly will print the status line and HTTP headers of each reply. See --prn_reqs option for details.

Name:--prn_errs
Type:boolean
Default:no
Version:2.1.0 only

When prn_errs is set, Polygraph will attempt to dump the status/request line and HTTP headers of each message that led to a xactions error. For some errors, a part of a message content is also printed. See --prn_reqs option for details.

Name:--notify
Type:host:port
Default:no default
Version:1.3.1 and up

The notify option instructs Poly to send status messages to a daemon on the specified host. The messages are small (about 100 bytes) and are sent using UDP protocol ensuring negligible overhead. The messages are emitted every 20 seconds.

Polygraph distribution comes with a listening daemon (udp2tcpd) and an interactive monitoring program (polymon).

Monitoring capabilities are very handy if you want to watch your experiments closely, but do not want to create extra load on the poly-machines. Polymon is also very helpful in maintaining several independent experiments.

Name:--label
Type:string
Default:no default
Version:1.3.1 and up

The label option allows you to assign a string label to a run. The label gets logged (as any other option value) and is also included into notification messages (see --notify). The latter is useful if you running several experiments and want polymon to distinguish them by a short ``name''.

Note that notification messages truncate labels to 15 characters, and polymon usually displays 6 first characters.

Name:--fd_limit
Type:int
Default:no default
Version:1.0p4 and up

Polygraph determines the maximum level of available file descriptors using getrlimit(RLIMIT_NOFILE) system call. It then attempts to set the current level to that maximum using the setrlimit(RLIMIT_NOFILE) system call. The return value of the latter (actually about 97% of it) is then used as a Polygraph internal FD limit.

Polygraph will not attempt to create more TCP sockets than its internal limit. However, some OSes are known to be unhappy when a process is close to the limit. In a non-production benchmarking environment, there may be also a competition for file descriptors with other processes. The fd_limit option can be used to lower the internal limit even further.

Polygraph will quit if it reaches its internal FD limit. In most cases, the log (if enabled using the --log option) will be flushed/saved before program termination.

One cannot raise the FD limit using the fd_limit option! The original limit is reported by the operating system and must be changed first. Different OSes will require different techniques for raising the file descriptor limits. Some well-known hacks can be found elsewhere.

Finally, note that two Polygraph header files (src/include/config.h and src/xstd/include/xstd.h are #defining FD_SETSIZE to be 4096. If you intend to use more file descriptors, you probably should increase that value. FD_SETSIZE is a system ``constant'' that is used for select(2) related calls on some OSes.

Name:--config
Type:filename
Default:no default
Version:2.0 and up

The --config option specifies configuration file for polygraph clients and/or servers. See Polygraph Language documentation for details on how to write a configuration file.

Root configuration file as well as #include files are searched for using the --cfg_dirs option.

Name:--cfg_dirs
Type:comma-separated list of directory names
Default:``./'' or current directory
Version:2.0 and up

The --config option specifies the list of directories that are searched for root configuration file as well as #include files. See --config option for how to specify a root configuration file. See Polygraph Language documentation for details on #include statements and how to write a configuration file.

Name:--console
Type:filename
Default:standard output (``-'')

Console option allows you to redirect console output into a file. The file must be reachable from the current directory.

Name:--log
Type:filename
Default:no default

This option enables preserving detailed stats in a log file.

Name:--log_size
Type:size
Default:10MB

All log content is kept in memory until the end of a run. This option allows you to specify the maximum log buffer size to hold that info. When logging module runs out of buffer space, it stops logging completely.

Logging must be enabled with the --log option first. If no --log option was specified, a small 10KB log is kept in memory and is discarded at the end of a run.

Polygraph versions 1.0p5 and earlier will exit when run out of log buffer space. These versions are using memory resident log buffer regardless of the --log option presence.

Name:--stats_cycle
Type:time
Default:5sec
Version:2.1.0 and up

Stats_cycle specifies the duration of Interval stats cycle. Shorter cycles give more precise statistics but result in larger binary logs.

Name:--linger_tout
Type:time
Default:no default
Version:discontinued in 2.0

Linger_tout is an equivalent of the SO_LINGER socket option. Omitting the option or specifying a special none value results in the default TCP behavior. In Poly releases after 1.0p0, setting timeout to zero is equivalent to setting SO_LINGER to "disabled" (see below). 

     SO_LINGER controls the action taken when unsent messages are
     queued on socket and a close(2) is performed.  If SO_LINGER
     is set, the system will block the process on the close(2)
     attempt until it is able to transmit the data or until it
     decides it is unable to deliver the information within the
     specified timeout. If SO_LINGER is set to "disabled" and a
     close(2) is issued, the system will process the close in a
     manner that allows the process to continue as quickly as
     possible.

Name:--nagle
Type:boolean
Default:true
Version:discontinued in 2.0

Nagle is an equivalent of the TCP_NODELAY protocol option. See Unix Socket FAQ for more info.

Name:--xact_think
Type:TimeDistribution
Default:no default
Version:discontinued in 2.0

Xact_think specifies the ``think time'' for each transaction.

On the server side, a transaction will sleep right after a connection is accepted and before reading the request.

On the client side, a transaction will sleep right before opening a connection and sending a request.

Name:--pconn_use_lmt
Type:NumDistribution
Default:no default
Version:1.1p0 and up; discontinued in 2.0

When first created, an HTTP connection is assigned the number of transactions it should be used for. That number is drawn from the distribution specified using the pconn_use_lmt option. A usage limit of 2 transactions or more implies a persistent connection (if the other side cooperates).

Pconn_use_lmt makes sense on both server and client sides. By default, all connections are used only once.

Poly-client or poly-server will close a connection if either the other side has sent ``Connection: close'' header or the connection usage limit has been reached. ``Proxy-Connection:'' headers are also honored. Polygraph indicates its intention to keep or close a connection by sending the appropriate Connection:'' header with every request.

Note: The Nagle algorithm may need to be turned off using the --nagle option. Otherwise, TCP ack packets are delayed for about 200msec resulting in 5req/sec throughput for a single TCP connection.

Name:--goal
Type:Goal
Default:no default
Version:discontinued in 2.0

Use the goal option to specify the termination conditions for an experiment. A termination condition can be experiment duration, number of successful transactions, or number of errors. At least one condition must be specified. Conditions are ORed together.

The order of conditions is flexible. The following simple heuristics are used to guess the actual order:

  1. first number if any is ``number of successful transactions''
  2. second number if any is ``number of errors''
  3. time if any is ``experiment duration''

Conditions are separated with a column (:). For example: 

polyclt --goal -1:1hour:1000 ...
would mean to stop an experiment in 1 hour or after 1000 errors. The number of successful transactions is unlimited.

Note that goal settings are also used to determine the termination condition for experiment phases.

Poly does not yet support termination based on number of xaction errors.

Name:--file_scan
Type:poll | select
Default:poll if supported; select otherwise
Version:1.3.0 and up

Most Unix operating systems have at least two system calls to detect ``ready'' file descriptors: poll(2) and select(2). The --file_scan option allows you to control which method to use. See manual pages for your OS for details about these system calls.

File scanning method may affect performance of Polygraph under heavy loads or when working with large number of file descriptors. The effect is probably limited to how fast Polygraph can scan all ready files. The ``best'' system call to use depends on the OS and the load on Polygraph. We suspect that performance differences are marginal in many general cases. Experiment if you want to double check your environment.

If you are still using Polygraph 1.x, and your OS does not support poll(2) system call, you have to add -DLACK_POLL to the DEFINES variable in src/xstd/Makefile. Otherwise, Polygraph will not compile. Recent versions of Polygraph do not have this problem. Also, Polygraph 1.x uses select(2) by default.

Name:fake_hosts
Type:comma-separated list of IPs
Default:no default
Version:2.0 and up

Polygraph configuration file binds robots and servers to specific IP addresses. Normally, polyclt and polysrv scan the list of network interfaces available on the host to determine which robots and servers to start. However, the default scan relies on semi-portable system calls and might not work correctly.

To disable the network interface scan, use the --fake_hosts option. The specified list of IP addresses will be used instead of the one obtained from the operating system.

Name:--idle_tout
Type:time
Default:infinity

By default, Polygraph will stop simulation when all phases reach their goals. Sometimes a phase has a goal that cannot be reached. Sometimes network or other external conditions stall all pending transactions. In these and similar situations it is often desirable to stop the simulation even if not all phases are completed.

The --idle_tout option is used to specify a finite time the server should wait for some network activity. If no network activity happens within the specified time, Polygraph will stop the simulation with an ``inactivity timeout'' message.

For Polygraph prior to version 2.0, the inactivity timeout could be specified on server side only.

Name:--rng_seed
Type:integer
Default:1

Rng_seed is used to initialize all random number generators. By varying the seed, one can test how susceptive to random noise the simulation is.

Name:--unique_world
Type:boolean
Default:false

If set to true, unique_world instructs Polygraph use only the random generator seed when generating URLs. By default, Polygraph will use other random factors such as time and process ID to make sure that the URLs do not repeat from one test to another. Use this option if you are trying to preserve the set of URLs across several (similarly configured) runs or across several (similarly configured) polysrv processes of the same test.

Unique_world is essentially a hack that you should avoid unless you know what you are doing. The option's name is unfortunate. It used to be called repeat, but that was even more confusing.

Name:--port
Type:integer
Default:no default
Version:discontinued in 2.0

The port option specifies the port a server should listen on. If you specify a port in a ``privileged'' range (i.e., [0-1023]), you have to start Polyserver as a root, give it an 's' bit, etc.

Usually, a Polyclient will use the same server port in the --origin option.

Name:--accept_lmt
Type:integer
Default:infinity
Version:discontinued in 2.0

Use the accept_lmt option to limit the number of connections that a server can accept(2) before it will try to process some of the active connections.

The default is to have no limit. The server will accept all connections waiting in the TCP listen queue before proceeding any further.

Specifying a low limit may lead to listen queue overflows and dropped connections on a busy system. With a high limit (or no limit) one may still have overflows; always check TCP settings and TCP statistics.

Name:--rep_sz
Type:SizeDistribution
Default:Exp(13KB)
Version:discontinued in 2.0

The rep_sz option specifies the reply content length distribution.

The actual reply sizes will vary depending on the object popularity model in use.

The rep_sz option specifies the mean reply size in early versions of Polygraph. Exponential distribution was hard-coded.

Name:--track_rports
Type:Boolean
Default:false
Version:discontinued in 2.0

Track_rports instructs Polyclt to monitor remote port usage. A remote port is the port on the proxy side of a proxy-server connection. Poly will report the first time a remote port was re-used and the minimum time between two consecutive uses of the same remote port. All values are currently reported as console comments. The minimum verbosity level to see the comments is two.

A possible application of the track_rports option is to measure minimum time remote (proxy) sockets spend in TIME_WAIT state. However, due to well-known violations of TCP by many BSD-derived systems, it may be impossible to measure TIME_WAIT state or MSL values accurately.

See also the rport_wait_min option.

Name:--rport_wait_min
Type:Time
Default:60 seconds
Version:discontinued in 2.0

When the track_rports option is enabled, Poly will report the minimum time (gap) between two consecutive uses of the same port seen so far. The rport_wait_min specifies the maximum gap to report. In other words, Poly will ignore all consecutive uses of the same port separated by more than rport_wait_min.

Name:--obj_bday
Type:TimeDistribution
Default:unif:10year,20year (random dates in the 1980's)
Version:1.2.1 and up; discontinued in 2.0

The obj_bday option specifies the creation time of objects or birthdays. For each object, a creation time is drawn from the specified distribution. The middle of the very first life cycle corresponds to that selected birthday. Naturally, object's birthday does not change during one simulation.

Negative values produced by a distribution are interpreted as offsets since program start. Non-negative values are offsets since Unix Epoch (00:00:00 January 1, 1970, UTC).

See Object Life Cycle model description for more information and examples.

Name:--obj_life_cycle
Type:TimeDistribution
Default:no default
Version:1.2.1 and up; discontinued in 2.0

The obj_life_cycle option specifies the distribution to use for selecting object life cycles. For a given object, the duration of the life cycle is selected once and stays the same afterwards.

See Object Life Cycle model description for more information and examples.

Name:--obj_life_cycle_var
Type:Ratio
Default:0%
Version:1.2.1 and up; discontinued in 2.0

By definition, an object is modified once per life cycle. The precise modification time within a given cycle is controlled by the obj_life_cycle_var option. If obj_life_cycle_var set to 0%, the modifications will always happen exactly in the middle of object cycle. If set to 100%, the object may be modified anytime from the beginning till the end of a cycle. Values higher than 100% might also be useful to simulate buggy servers.

See Object Life Cycle model description for more information and examples.

Name:--obj_with_lmt
Type:Ratio
Default:0%
Version:1.2.0 and up; discontinued in 2.0

The obj_with_lmt options simply specifies the portion of objects that will announce their modification times via the Last-Modified: header field. You must enable the --obj_life_cycle option to generate the actual modification times.

See Object Life Cycle model description for more information and examples.

Name:--obj_expire
Type:ObjExpire
Default:no default
Version:1.2.0 and up; discontinued in 2.0

The obj_expire option(s) configure the object expiration model in Polygraph. Currently two expiration algorithms are supported: based on last modification time and based on current time.

See Object Life Cycle model description for more information and examples.

The syntax for the obj_expire option is 

	<ratio> = 'now' + <TimeDistribution>
or
	<ratio> = 'lmt' + <NumDistribution>
Where ratio specifies the portion of objects that will be affected by the corresponding algorithm/formula. If the ratios specified using obj_expire option(s) do not add up to 100%, then the rest of the objects are assumed to have unknown expiration time, and no Expires: header fields is generated for them.

There must be no spaces between tokens. Again, the examples are available elsewhere


$Id: srvopts.sml,v 1.12 1999/10/12 19:20:33 rousskov Exp $