userver(1)                                                          userver(1)



[1mNAME[0m
       userver - Micro-server
       (A fairly simple web server designed for experimentation)

[1mSYNOPSIS[0m
       [1muserver[0m

       [[1m-A[22m|[1m--accepts-only[22m]      [[1m-A[22m|[1m--close-after-accept[22m]     [[1m-B[22m|[1m--block-for-[0m
       [1msend_events[22m] [[1m-C[22m|[1m--caching-on[22m] [[1m-D[22m|[1m--debug-mask [4m[22m0xN[24m] [[1m-E[22m|[1m--send-events[22m]
       [[1m-F[22m|[1m--reset-on-close[22m]  [[1m-G[22m|[1m--use-getpid[22m]  [[1m-H[22m|[1m-h[22m|[1m-?[22m|[1m--help[22m]  [[1m-I[22m|[1m--rcv-[0m
       [1msock-low-wat  [4m[22mN[24m]  [[1m-J[22m|[1m--snd-sock-low-wat  [4m[22mN[24m]   [[1m-K[22m|[1m--kdebug-mask   [4m[22m0xN[24m]
       [[1m-L[22m|[1m--full-read  [4m[22mN[24m]  [[1m-M[22m|[1m--multi-accept[22m] [[1m-N[22m|[1m--send-loop[22m] [[1m-O[22m|[1m--select-[0m
       [1mtimeout [4m[22mN[24m] [[1m-P[22m|[1m--count-sigpipes[22m] [[1m-Q[22m|[1m--ecb-hi-water [4m[22mN[24m] [[1m-R[22m|[1m--read-sock-[0m
       [1mbuf-size  [4m[22mN[24m]  [[1m-S[22m|[1m--dont-intr-select[22m]  [[1m-T[22m|[1m--port [4m[22mN[24m] [[1m-U[22m|[1m--auto-accept[22m]
       [[1m--auto-accept-aperture[22m]  [[1m-W[22m|[1m--write-sockbuf-size  [4m[22mN[24m]   [[1m-Y[22m|[1m--send-io-[0m
       [1mevents[22m]  [[1m-a[22m|[1m--async-mode[22m]  [[1m-b[22m|[1m--ecb-buf-entries [4m[22mN[24m] [[1m-c[22m|[1m--max-conns [4m[22mN[24m]
       [[1m-d[22m|[1m--delay [4m[22mN[24m] [[1m-e[22m|[1m--extra-accepts [4m[22mN[24m] [[1m-f[22m|[1m--max-fds [4m[22mN[24m] [[1m-g[22m|[1m--accept-on-[0m
       [1mclose[22m]  [[1m-i[22m|[1m--interactive[22m] [[1m-j[22m|[1m--kernel-info[22m] [[1m-k[22m|[1m--sigio-use-procmask[22m]
       [[1m-l[22m|[1m--listenq [4m[22mN[24m] [[1m-m[22m|[1m--accept-count [4m[22mN[24m] [[1m-n[22m|[1m--no-accepts[22m]  [[1m-n[22m|[1m--listen-[0m
       [1monly[22m]        [[1m-o[22m|[1m--process-fd-order        [22m[[1mup[22m|[1mdown[22m|[1mwrites-down[22m|[1mwrites-[0m
       [1mup[22m|[1mlru[22m|[1mlifo[22m|[1mfifo[22m][1m] [22m[[1m-p[22m|[1m--procs [4m[22mN[24m] [[1m-q[22m|[1m--ecb-low-water  [4m[22mN[24m]  [[1m-r[22m|[1m--eager-[0m
       [1mreads[22m]     [[1m-s[22m|[1m--conns-in-server-loop[22m]    [[1m-t[22m|[1m--free-fd-threshold    [4m[22mN[24m]
       [[1m-u[22m|[1m--track-max-fd    [4m[22mN[24m]    [[1m-w[22m|[1m--eager-writes[22m]    [[1m-x[22m|[1m--sigio-accepts[22m]
       [[1m-y[22m|[1m--memcpy[22m] [[1m-z[22m|[1m--rejection-rate[22m] [[1m--close-after-sock-init[22m] [[1m--close-[0m
       [1mafter-read[22m] [[1m--close-after-parse[22m] [[1m--send-polls-for-accepts[22m]  [[1m--cache-[0m
       [1mtable-size [4m[22mN[24m] [[1m--cache-max-bytes [4m[22mN[24m] [[1m--cache-max-file-size [4m[22mN[24m] [[1m--cache-[0m
       [1mmax-load-factor [4m[22mN[24m] [[1m--cache-table-print[22m] [[1m--cache-lock-pages[22m] [[1m--cache-[0m
       [1mfor-spec[22m]    [[1m--use-sendfile[22m]    [[1m--use-accept-send[22m]    [[1m--use-madvise[22m]
       [[1m--trace-summary[22m]  [[1m--trace-summary-only[22m]  [[1m--use-poll[22m]   [[1m--use-epoll[22m]
       [[1m--use-epoll2[22m] [[1m--use-epoll-ctlv[22m] [[1m--ip-addr [4m[22mN[24m] [[1m--stats-interval [4m[22mN[24m]


[1mDESCRIPTION[0m
       [1muserver  [22mis  a  micro web server that is meant to be used to experiment
       with the design and implementation of web servers.  In  particular  the
       original  intention was to permit experimental comparisons of different
       event dispatch mechanisms within the same appliication framework.   For
       this  reason  there are lots and lots and lots of parameters.  They are
       mainly used to control the behaviour of the server.

       Some of the design philosophy and experimental results  obtained  using
       this  server  are  described in [Brecht-2001].  One of note is that all
       data structures are allocated at initialization  and  are  not  resized
       (grown).  This helps to ensure that experiments can be repeated because
       with dynamic sizing of data structures different loads could result  in
       different server behaviour.

       The  userver uses an event driven architecture.  The idea is to run one
       event driven server per processor.  If using sendfile on Linux the file
       system buffer cache will be shared across all servers. For high-perfor-
       mance one would want to use sendfile since  it  doesn't  involve  extra
       copying from the file buffer cache to socket buffers (i.e., it's a zero
       copy implementation).


       [1mIMPORTANT: [22mThis micro web server is not meant to be  a  full-blown  web
       server.  It is specifically designed for conducting performance experi-
       ments.  For that reason design decisions were made in favour of produc-
       ing repeatable experiments.


[1mEXAMPLES[0m
       userver
              This starts the [1muserver [22mwith it's all of its default options.


       userver --max-conns 300 --accept-count 25
              This  command  causes  the [1muserver [22mserver to limit the number of
              simultaneous connections to 300.  When an event indicating  that
              a  new  connection  is  requested  accept is called continuously
              until either 25 new connections are accepted, or  there  are  no
              more outstanding connections.


       userver --max-conns 300 --accept-count 0
              This  command  causes  the [1muserver [22mserver to limit the number of
              simultaneous connections to 300.  When an event indicating  that
              a  new connection is requested accept is called repeatedly until
              there are no more outstanding connections.  (Note that --accept-
              count=0  means  an infinite number of connections, i.e., no lim-
              its).


       userver --ip-addr 192.168.10.105 --max-conns 300 --listenq 128

       userver --ip-addr 192.168.20.105 --max-conns 300 --listenq 128
              This will start up two copies of the userver each accepting con-
              nections from a different interface.


       userver --ip-addr 192.168.10.105:6801 --max-conns 300 --listenq 128

       userver --ip-addr 192.168.20.105:6802 --max-conns 300 --listenq 128
              Same  as  above except one listens on port 6801 and the other on
              port 6802.


       userver --port 6800 --max-conns 300 --listenq 128
              This command causes [1muserver [22mto listen  for  incoming  connection
              requests on port 6800.  It uses a listen queue of length 128 and
              it will permit up to 300 simultaneous connections.   Once  there
              are  300  open  connections  it  will not accept new connections
              until an existing connection is closed.


       userver --port 6800 --max-conns 300 --listenq 128 --use-poll
              This is the same as above except using  [4mselect()[24m  calls  to  get
              events the [1muserver [22mwill use [4mpoll().[0m


       userver --port 6800 --max-conns 300 --listenq 128 --use-epoll
              This  is  the  same  as  above  except using [4mpoll()[24m calls to get
              events the [1muserver [22mwill use [4mepoll().[0m


       userver   -C    --cache-table-size=10000    --cache-max-bytes=262144000
       --cache-max-file-size=1048576
              Caching is turned on.  Caching parameters limit  the  number  of
              files that are cached to 10000, the total number of bytes cached
              to 250 MB, and the size of the largest file that can  be  cached
              to 1 MB.


[1mOPTIONS[0m

       The operation of [1muserver [22mcan be controlled through a number of options.
       The tool supports  both  short  (one-character)  and  long  (arbitrary-
       length) option names.  Short options are prefixed with a single leading
       dash (-), long options with a double-dash (--).  Multiple short options
       can  be grouped together (e.g., ``[1m-rw[22m'' is equivalent to ``[1m-r -w[22m'') and
       long options can be abbreviated so long as they remain unique.  Parame-
       ters  to  options  can be specified either by following the long option
       name with an equal sign and the parameter value (e.g., [1m--port=6800[22m)  or
       by  separating  the option name and value with whitespace (e.g., [1m--port[0m
       [1m6800[22m).


[1mOPTIONS (GENERAL)[0m


       [1m-c N[0m

       [1m--max-conns=[4m[22mN[0m
              The maximum number of simultaneous connections the  server  will
              handle.   Note  that  this is typically limited by the number of
              open file descriptors permitted.  Once  the  maximum  number  of
              open  connections  is  reached  incoming connection requests are
              refused until an existing connection is close.  Note  that  idle
              connections  can  be  timed out eventually (but this hasn't been
              tested lately).  This is also used to size a number of  internal
              data structures that are allocated at initialization time.


       [1m-f N[0m

       [1m--max-fds=[4m[22mN[0m
              The  maximum number of open file descriptors permitted.  I can't
              recall if this is actually enforced  but  it  is  used  to  size
              internal  data  structures.   Note  that there is a relationship
              between [1m--max-conns [22mand  [1m--max-fds.   [22mIf  files  are  not  being
              cached  you could (in the extreme case) have one fd used for the
              socket connection and one fd used for the  open  file.   So  one
              needs  to  set  [1m--max-fds [22m= more than 2 x [1m--max-conns.  [22mNote: it
              should be greater because of some descriptors that are  used  up
              by stdin, out, err, and a few open files, etc.


       [1m-m N[0m

       [1m--accept-count=[4m[22mN[0m
              Call  accept  repeatedly  until  either, [1m--max-conns [22mis reached,
              [1maccept() [22mreturns EWOULDBLOCK, or [4mN[24m  new  connections  have  been
              accepted.   Note that the value of [4mN[24m can make a substantial dif-
              ference in the performance of event  dispatch  mechanisms  under
              heavy loads.  See [Brecht-2001].


       [1m-T N[0m

       [1m--port=[4m[22mN[0m
              Specify  the  port number that the server should listen for con-
              nections on.


       [1m-l N[0m

       [1m--listenq=[4m[22mN[0m
              Specify the length of the appliation's listen queue.  This spec-
              ifies  how  many connection requests are allowed to be queued in
              the application before the kernel  rejects  incoming  connection
              requests.


       [1m-L[22m[1 | 2]

       [1m--full-read=[22m[1 | 2]
              Affects  how calling read works.  If this is set to 1 the server
              will loop on reading the socket  until  the  read  fails.   This
              mainly  happens  either  because  there  is nothing left to read
              because the other end has been closed or  until  it  would  have
              blocked (EWOULDBLOCK).

              If  a  value  of  1 is used the loop on reads will only occur on
              calls to read that occur as a result of an event indicating that
              the first read should be done.  If a value of 2 is used the loop
              on reads occur as above but if [1m--eager-reads  [22mis  also  set  the
              server  will  loop on eager reads (i.e., those that will be done
              immediately following a the acceptance and setup  of  a  connec-
              tion).


       [1m-H[0m

       [1m-h[0m

       [1m-?[0m

       [1m--help [22mPrint out the usage message.


       [1m-M N[0m

       [1m--multi-accept=[4m[22mN[0m
              Use  the  [4mmultiaccept()[24m  system  call to perform accepts.  NOTE:
              this was a system call that we added to and experimented with in
              Linux.   The  idea  here is that since we are repeatedly calling
              [4maccept()[24m to accept a bunch of connections,  why  not  provide  a
              system  call  that allows up to a maximum of [4mN[24m connections to be
              accepted in one system call.


       [1m-S[0m

       [1m--dont-intr-select[0m
              Disable asynchrnous event notification when calling [4mselect().[24m  I
              believe  that this was initially meant to work for SIGIO and for
              SEND.


       [1m-d N[0m

       [1m--delay=[4m[22mN[0m
              The idea was to introduce a delay that might simulate work being
              done  by  the  server  (like  some  computation and/or a dynamic
              request).  I couldn't find a good  method  for  delaying  for  a
              specified  amount  of time (note that it should be small) with a
              enough accuracy.


       [1m-e N[0m

       [1m--extra-accepts=[4m[22mN[0m
              While in the middle of processing events that have been obtained
              (e.g.,  from  select, or some other mechansim) periodically poll
              for new connection requests.  In this case every time [4mN[24m descrip-
              tors  are  processed we check for new connection requests.  Note
              that this open was never used effectively.  I found it easier to
              use and tune the [1m--accept-count [22moption.


       [1m-g[0m

       [1m--accept-on-close[0m
              When  a  connection is closed check to see if there are any out-
              standing connection requests.  Note: that this  only  occurs  if
              the  maximum  number of connections was reached and now a closed
              connection will reduce the number of  connections  below  [1m--max-[0m
              [1mconns.[0m


       [1m-o [up|down|writes-down|writes-up|lru|lifo|fifo][0m

       [1m--process-fd-order[0m
              [up|down|writes-down|writes-up|lru|lifo|fifo]

              Change  the  order  in which file descriptors are handled.  They
              are numbered from 0 to [4mN[24m so the uptions are:

              up:    from 0 to N

              down:  from N to 0

              writes-down:
                     to writes from N to 0, then reads from N to 0

              writes-up:
                     to writes from 0 to N, then reads from 0 to N

              lru:   least recently descriptor touched first

              lifo:  first descriptor (connection) added to the set first

              filo:  first descriptor (connection) added to the set last


       [1m-p N[0m

       [1m--procs=[4m[22mN[0m
              Start [4mN[24m copies of the server.  Note that this option hasn't been
              tested in a long time and is almost certain to cause problems.


       [1m-s[0m

       [1m--conns-in-server-loop[0m
              Add an additional poll for new connections each time through the
              server loop.


       [1m-t N[0m

       [1m--free-fd-threshold=[4m[22mN[0m
              When the maximum number of connections  [1m--max-conns  [22mis  reached
              the  server  stops  checking  for  incoming  connections.   This
              options controls when the  server  starts  checking  again.   It
              starts  checking  again  after  [4mN[24m connections can be accomodated
              before reaching [1m--max-conns.[0m


       [1m-u[0m

       [1m--track-max-fd[0m
              The server currently keeps track of the maximum fd ever used and
              uses  that  as  a  parameter  to calls like select.  This option
              implements code to dynamically keep track of  the  maximum  file
              descriptor  currently  used.   Note  that this requires a bit of
              extra processing but it's probably not noticable, especially  if
              it can save estra overhead on copying fdsets and processing time
              in event mechanisms (e.g., select).


       [1m-r[0m

       [1m--eager-reads[0m
              try to eagerly read from new connections.  Call [1mread() to try to[0m
              [1mread  the request as soon as [22mthe new connection is accepted.  In
              this mode the server optimistically assumes that  data  will  be
              available  for reading when a connection is made on a new socket
              (or very shortly after).  If the assumption  is  incorrect,  the
              read  call simply returns with the error EWOULDBLOCK.  Later the
              event notification mechanism will indicate when  the  socket  is
              readable.


       [1m-w[0m

       [1m--eager-writes[0m
              try  to  eagerly  perform  writes  to  new  connections when the
              response is available.  Both [1m--eager-read [22mand [1m--eager-write [22malso
              try to take advantage of any potential locality effects by work-
              ing on the most recently used file descriptor and socket.


       [1m-y[0m

       [1m--memcpy[0m
              Use the [1mmemcpy [22mlibrary call to copy interest sets before calling
              select.   This  is done rather than doing a straight assignment.
              This exists because the size of the interest set could be  large
              and  I don't know how clever a compiler would be about assigning
              large data structures.  NOTE: it currently copies the side of an
              fd_set.   This should be changed to only copy the amount of data
              required for the maximum fd of interest.


       [1m-z[0m

       [1m--rejection-rate[0m
              Use the [1mrejection-rate [22mis not yet implemented.  The ideas  would
              be  to  specify the frequency with which new connection requests
              should be rejected.


       [1m--use-sendfile[0m
              Use the [1msendfile() [22mcall on systems that have it available.  This
              is only used for uncached files.


       [1m--use-madvise[0m
              Use  madvise() calls to provide the kernel with hints that files
              are being read sequentially and when they should  no  longer  be
              cached.


       [1m--use-poll[0m
              Use poll() to get events instead of select.


       [1m--use-epoll[0m
              Use epoll() to get events instead of select.


       [1m--use-epoll2[0m
              Use  epoll()  to  get  events instead of select but attempt some
              optimizations to reduce the number of epoll_ctl calls.  We found
              the  number  of  epoll_ctl calls to be excessive so this options
              calls epoll_ctl when a new connection  is  added  and  sets  the
              interest  to  be READ and WRITE.  This means that epoll_wait may
              return events that we aren't interested in (e.g., that a  socket
              is  writable even though we are busy reading) but we are explor-
              ing the tradeoffs between the two  approaches  (--use-epoll  and
              --use-epoll2).


       [1m--use-epoll-ctlv[0m
              Use  epoll_ctlv()  to update events.  This requires the addition
              of a new system call, epoll_ctlv.  This call permits one to col-
              lect  a  bunch of epoll_ctl calls and change interest in a bunch
              of fds  at  once  instead  of  having  to  do  one  system  call
              (epoll_ctl) per change.


       [1m--ip-addr N[0m

       [1m--ip-addr N:P[0m
              Specify an IP address to listen for new connections on.  Option-
              ally takes a port number P as well.  The  special  option  --ip-
              addr  0.0.0.0  specifies  that  the userver should listen on any
              address (this is the default).


       [1m--stats-interval N[0m
              Print out some simple stats about related to server  performance
              at a regularly specified interval.  The interval is specified in
              seconds.  NOTE:  this  options  overrides  the  --select-timeout
              option  in  order to be able to print out stats according to the
              selected interval.


[1mOPTIONS FOR CONTROLLING SOCKETS[0m


       [1m-F[0m

       [1m--reset-on-close[0m
              Calls [4mshutdown()[24m instead of [4mclose().[0m
              WARNING do not use this for a real system!!!


       [1m-I N[0m

       [1m--rcv-sock-low-wat=[4m[22mN[0m
              Sets the sockets receive buffer's low  water  mark  to  [4mN.[24m   Not
              available on all systems.


       [1m-J[22mN

       [1m--snd-sock-low-wat=[22mN
              Sets  the sockets send buffer's low water mark to [4mN.[24m  Not avail-
              able on all systems.


       [1m-O N[0m

       [1m--select-timeout=[4m[22mN[0m
              Set the timeout option to the [4mselect()[24m system call.


       [1m-R N[0m

       [1m--read-sockbuf-size=[4m[22mN[0m

       [1m-W N[0m

       [1m--write-sockbuf-size=[4m[22mN[0m
              Set the size of the read or write  socket  buffers.   Note  that
              increasing these may help significantly for large transfers.


       [1m--use_tcp_cork[0m
              Cork  the TCP queue when writing the header for the reply.  Cur-
              rently only implemented for the sendfile portion of the code.


[1mOPTIONS FOR USE WITH SIGIO[0m


       [1m-a[0m

       [1m--sigio-accepts[0m
              Use asynchronous notification via SIGIO to  accept  new  connec-
              tions.   Asynchronous notification may sound costly at first but
              consider that some form of asynchronous notificaion may  be  the
              only  way  for an application that is in the middle of something
              (e.g., computation) to find out about a connection requests.


       [1m-k[0m

       [1m--sigio-use-procmask[0m
              To disable and later enble asynchronous notification of incoming
              requests when using SIGIO one can use [1mfcntl() [22mto turn off and on
              asynchronous notification or use [1msigprocmask().  [22mBe  careful  of
              race  conditions.   By  default the server uses [1mfcntl() [22mbut this
              option says to use [1msigprocmask() [22minstead.

[1mOPTIONS FOR CACHING[0m


       [1m-C[0m

       [1m--caching-on[0m
              Turns caching on.


       [1m--cache-table-size=[4m[22mN[0m
              Specifies the size of the hash table used to cached files.   One
              entry  is  used per cached file.  NOTE: if the [1m--cache-max-load-[0m
              [1mfactor [22mis exceeded the server will print a message and exit.  We
              do not automatically increase the size of the hash table because
              we want to ensure identical and repeatable  behaviour  from  one
              experiment to the next.


       [1m--cache-max-load-factor=[4m[22mN[0m
              Specifies  the  maximum  number of entries that can be filled in
              the hash table, expressed as a percentage  of  the  table  size.
              For  example  [1m--cache-max-load-factor  =  70 [22mwill not permit the
              hash table to become greater than 70% full.  If it does, a  mes-
              sage is printed and the server exits.


       [1m--cache-max-bytes=[4m[22mN[0m
              Specifies the maximum number of bytes cached.


       [1m--cache-max-file-size=[4m[22mN[0m
              Don't cache files larger than [4mN[24m bytes.


       [1m--cache-table-print[0m
              When  the program ends, print out the contents of the hash table
              used for caching.


       [1m--cache-for-spec[0m
              This enables a special hash function that does  perfect  hashing
              on URLs requested by SpecWeb99.  This is intended for experimen-
              tation only.


       [1m--cache-lock-pages[0m
              Lock all cached pages into memory (must run as root for this  to
              work).


[1mOPTIONS FOR DEBUGGING[0m


       [1m-D 0xN[0m

       [1m--debug-mask=[4m[22m0xN[24m[1m][0m
              Specify a debug mask.  For maximum debugging detail use [1m--debug-[0m
              [1mmask = [4m[22m0xffffffff.[24m  To turn debugging messages off use  [1m--debug-[0m
              [1mmask  =  [4m[22m0x0.[24m   See  debug.h for details.  Note: that to compile
              without debugging also see debug.h.


       [1m--trace-summary[0m
              Keep track of information regarding system  calls  and  print  a
              summary.   If  tracing  is  enabled  a  list of each event being
              traced will be dumped to a trace output file.


       [1m--trace-summary-only[0m
              Keep track of information regarding system  calls  and  print  a
              summary.   If  this  option is enabled individual events are not
              actually recorded but instead information to produce  a  summary
              of each event type is tracked. For example, minimum, maximum and
              average call times for each system call being traced.


       [1m-i[0m

       [1m--interactive[0m
              Turns on interactive mode.  The server stops  between  calls  to
              process events and prompts the user for input.  This permits the
              user to query some of the state of the server or to step through
              server  execution.   At the prompt type 'h' or '?' for a list of
              commands.


       [1m-P[0m

       [1m--count-sigpipes[0m
              Install a signal handler that simply counts the number  of  SIG-
              PIPE signals received.

[1mOPTIONS FOR EXPERIMENTS RELATED TO BOUNDING PERFORMANCE[0m

       These options are designed to have the server stop processing a request
       at various stages of a requests life.  It stops handling the request by
       closing it's end of the socket and not working on that request anymore.
       I've attempted to list these in the order of earliest time to drop  the
       request to latest.  The idea is that by running a series of experiments
       by using each of these options one might be able to get a sense of  how
       much additional stage costs.


       [1m-n[0m

       [1m--no-accepts[0m

       [1m--listen-only[0m
              This  puts  the server into a mode where it only ever listens to
              requests.  It never makes any attempt to process  requests.   So
              it  never  even  accepts any requests.  The believe is that this
              might be used to provide insights into the  amount  of  overhead
              incurred  when  kernel  TCP  SYN  queues  and application listen
              queues become full.


       [1m-A[0m

       [1m--accepts-only[0m

       [1m--close-after-accept[0m
              In this mode the server accepts and closes  incoming  connection
              requests  as  quickly  as  possible.   At the time this was done
              [4mclose()[24m would block until the call  completed  (despite  the  fd
              being  in  non  blocking  mode).   So  immediately after calling
              [4maccept()[24m the connection terminated by calling [4mclose().[0m


       [1m--close-after-sock-init[0m
              The server accepts a connection, initializes the socket (setting
              socket options like socket buffer sizes, non blocking mode, etc)
              and then it closes the connection.


       [1m--close-after-read[0m
              The server accepts a connection, initializes  the  socket  reads
              the request and then closes the connection.


       [1m--close-after-parse[0m
              The  server  accepts  a connection, initializes the socket reads
              the request, parses the requests and then closes the connection.

[1mOPTIONS FOR USE WITH THE SEND ENHANCED KERNEL[0m

       WARNING:  these options are highly experimental and subject to continu-
       ous change.

       These options specify how the [1muserver [22minteracts with new Linux Scalable
       Event   Notification   and  Delivery  (SEND)  kernel  mechanisms.   See
       [Ostrowski-2000] for more details on SEND.


       [1m-K 0xN[0m

       [1m--kdebug-mask=[4m[22m0xN[24m[1m][0m
              Specify a debugging mask which is passed to  the  [4mevtctl[24m  system
              call  to  set a kernel debugging mask for the SEND related parts
              of the kernel.


       [1m--send-polls-for-accepts[0m
              The send loop polls for new connections.


       [1m-B[0m

       [1m--block-for-send_events[0m
              When there are not more events to process, block  and  wait  for
              one or more new events by calling [4mevtctl().[0m


       [1m-E[0m

       [1m--send-events[0m
              Use send events. This version does not do notification.


       [1m-G[0m

       [1m--use_getpid[0m
              If  we aren't blocking to wait for events (by calling evtctl) we
              may wish to make a system call to give the kernel  a  chance  to
              deliver events to the application (since they are delivered when
              returning from a syscall.  In this case we use getpid()  because
              it is likely fast.


       [1m-Y[0m

       [1m--send-io-events[0m
              Use send events. This version does do notification.


       [1m-N[0m

       [1m--send-loop[0m
              Use  the send loop.  Can potentially get and process send events
              even while using select.  This bypasses the use  of  the  select
              call.


       [1m-b N[0m

       [1m--ecb-buf-entries=[4m[22mN[0m
              How many events can be stored in the application's event control
              buffer (ecb).


       [1m-Q N[0m

       [1m--ecb-hi-water=[4m[22mN[0m
              Set the high water mark used for the event control buffer (ecb).
              One of the things we've tried is to turn event delivery off when
              the [4m--ecb-hi-water[24m mark is reached and  then  to  turn  delivery
              back on when the [4m--ecb-low-water[24m mark is reached.


       [1m-q N[0m

       [1m--ecb-low-water=[4m[22mN[0m
              Set  the low water mark used for the event control buffer (ecb).
              One of the things we've tried is to turn event delivery off when
              the  [4m--ecb-hi-water[24m  mark  is  reached and then to turn delivery
              back on when the [4m--ecb-low-water[24m mark is reached.


       [1m-U[0m

       [1m--auto-accept[0m
              Turn on the SEND kernel's auto accept mechanisms.  When new con-
              nection  requests  arrive  the kernel automatically accepts them
              (auto accepts 'em) and notifies the application  with  an  event
              containing the new connection's fd.


       [1m--auto-accept-aperture[0m
              Control  the  difference  between  the number of connections the
              kernel has  autoaccepted  and  the  number  of  connections  the
              application  has  closed.   Without  this  type  of  control the
              autoaccepting can get out of control and the  kernel  can  spend
              too much time auto accepting new connections and the application
              is not able to make much forward progress  on  existing  connec-
              tions.


       [1m--use-accept-send[0m
              Use  a  special version of accept that returns event information
              related to the accepted connection/socket.


       [1m-j[0m

       [1m--kernel-info[0m
              Experimental: was to tell the application that the kernel has an
              interface  available  for  obtaining  more information about the
              size and number of entries in some of the kernel  queues  (e.g.,
              the TCP SYNQs and the application's listenq).

[1mOUTPUT[0m
       This  section describes portions of the output produced during the exe-
       cution of the [1muserver.[0m


       The first portion of output lists the program name and the command line
       parameters.   The  second  portion  of  output lists the setting of all
       options.  This is the most reliable way to find out  the  default  set-
       tings for some options.


       The next two sections identify operating system and per user or process
       limits.

       The remainder of the output provides  more  information  about  default
       settings  of  various parameters and a large number of statistics about
       the execution of the server.


[1mAUTHORS[0m
       [1muserver [22mwas developed by Tim Brecht by starting  with  some  micro  web
       servers  originally  developed  by Abhishek Chandra and David Mosberger
       [Chandra-2001].  David Pariag contributed the current  caching  engine.
       One of the hash functions is from Bob Jenkin's web site.


[1mBUGS[0m
       Probably many.

       NOTE: very few if any checks are performed to see if the combination of
       options being used makes sense.  For example, the behaviour from  using
       both the [1m--select-loop [22mand [1m--send-loop [22moptions is undefined.

       Always be sure to double-check results and don't fall prey to measuring
       client-performance instead of server performance!  The tool [1mhttperf  [22mis
       very good at generating loads.

       Many  of  the single letter options are difficult to relate to anything
       meaningful. As the number of options grew I eventually started  to  run
       out of alphabet and added long options.

       The  user-interface  definitely could be improved.  A simple configura-
       tion file might be more suitable than the many command-line options.


[1mREFERENCES[0m
       [Brecht-2001]    Tim Brecht and Michal Ostrowski, Exploring the Perfor-
                        mance  of Select-based Internet Servers, HP Labs Tech-
                        nical Report HPL-2001-314, November, 2001.


       [Chandra-2001]   A. Chandra and  D.  Mosberger,  Scalability  of  Linux
                        Event-Dispatch  Mechanisms,  Proceedings  of  the 2001
                        USENIX Annual Technical Conference, June 2001.


       [Ostrowski-2000] Michal Ostrowski, A Mechanism for Scalable Event Noti-
                        fication and Delivery in Linux, M.Math Thesis, Depart-
                        ment of  Computer  Science,  University  of  Waterloo,
                        November, 2000.



                                  1 Aug 2003                        userver(1)
