Provided by: hobbit_4.2.0.dfsg-12_i386 bug

NAME

       bbproxy - Hobbit / Big Brother message proxy

SYNOPSIS

       bbproxy [options] --bbdisplay=$BBDISP

DESCRIPTION

       bbproxy(8)  is  a  proxy  for  forwarding Big Brother messages from one
       server to another. It will typically be  needed  if  you  have  clients
       behind a firewall, so they cannot send status messages to the BBDISPLAY
       server directly.

       bbproxy serves three purposes.  First,  it  acts  as  a  regular  proxy
       server,  allowing clients that cannot connect directly to the BBDISPLAY
       or BBPAGER servers  to  send  messages  to  the  Big  Brother  servers.
       Although  bbproxy  is  optimized  for handling status messages, it will
       forward all types of messages, including notes- and data-messages.  The
       standard  Big  Brother  daemon, bbd(1) can also do this via the BBRELAY
       setting. However, bbproxy has a much lower overhead since it runs as  a
       single-thread  application  and does not launch new processes to handle
       each incoming message.

       Second, it acts as a buffer, smoothing out peak loads if  many  clients
       try  to  send  status  messages  simultaneously.   bbproxy  can  absorb
       messages very quickly, but will queue them up  internally  and  forward
       them  to the BBDISPLAY server at a reasonable pace. This helps even out
       the load on your BBDISPLAY server.

       Third, bbproxy merges  small  "status"  messages  into  larger  "combo"
       messages. This can dramatically decrease the number of connections that
       need to go from  bbproxy  to  the  BBDISPLAY  server,  and  since  each
       connection  to the BBDISPLAY server requires a new proces to be started
       this will also cut down on the  load  on  your  BBDISPLAY  server.  The
       merging  of  messages  causes "status" messages to be delayed for up to
       0.25 seconds before being sent off to the BBDISPLAY server.

OPTIONS

       --hobbitd
              Enable this option when  the  destination  server  is  a  Hobbit
              server, not the Big Brother bbd daemon.

       --bbdisplay=SERVERIP[:PORT][,SERVER2IP[:PORT]]
              Specifies  the IP-address and optional portnumber where incoming
              messages are forwarded to. The default portnumber is  1984,  the
              standard  Big  Brother port number. If you have setup the normal
              Big Brother environment, you can use  "--bbdisplay=$BBDISP".  Up
              to 3 servers can be specified; incoming messages are sent to all
              of them (except "config", "query" and "download" messages, which
              go  to the LAST server only). If you have Hobbit clients sending
              their data via this proxy, note that the  clients  will  receive
              their  configuration  data  from  the LAST of the servers listed
              here.  This option is required.

       --bbpager=SERVERIP[:PORT][,SERVER2IP[:PORT]]
              DEPRECATED - this option is only present for compatibility  with
              servers   running   Big  Brother,  and  will  be  removed  soon.
              Specifies the IP-address and optional portnumber where  incoming
              "page"  messages  are  forwarded  to.  The default portnumber is
              1984, the standard Big Brother port number. If  you  have  setup
              the    normal    Big    Brother   environment,   you   can   use
              "--bbpager=$BBPAGE". Up to 3 servers can be specified;  incoming
              messages  are  sent  to  all of them. If this option is omitted,
              "page" messages are sent to the servers listed in --bbdisplay.

       --listen=LOCALIP[:PORT]
              Specifies the  IP-adress  where  bbproxy  listens  for  incoming
              connections.  By  default,  bbproxy  listens  on all IP-adresses
              assigned to the host. If no portnumber is given, port 1984  will
              be used.

       --timeout=N
              Specifies  the  number  of  seconds  after which a connection is
              aborted due to a timeout. Default: 10 seconds.

       --report=[PROXYHOSTNAME.]BBSERVICE
              If given, this option causes bbproxy to  send  a  status  report
              every  5  minutes  to  the BBDISPLAY server about itself. If you
              have set the standard  Big  Brother  environment,  you  can  use
              "--report=bbproxy"  to  have  bbproxy  report  its  status  to a
              "bbproxy" column in Big Brother. The default  for  PROXYHOSTNAME
              is  the  $MACHINE environment variable, i.e. the hostname of the
              server  running  bbproxy.  See  REPORT  OUTPUT  below   for   an
              explanation of the report contents.

       --lqueue=N
              Size of the listen-queue where incoming connections can queue up
              before being processed.  This  should  be  large  to  accomodate
              bursts of activity from clients. Default: 512.

       --daemon
              Run  in daemon mode, i.e. detach and run as a background proces.
              This is the default.

       --no-daemon
              Runs bbproxy as a foreground proces.

       --pidfile=FILENAME
              Specifies the location of a file containing the proces-ID of the
              bbproxy daemon proces. Default: /var/run/bbproxy.pid.

       --logfile=FILENAME
              Sends  all  logging  output  to  the  specified  file instead of
              stderr.

       --log-details
              Log details (IP-address,  message  type  and  hostname)  to  the
              logfile.   This  can also be enabled and disabled at run-time by
              sending the bbproxy proces a SIGUSR1 signal.

       --debug
              Enable debugging output.

REPORT OUTPUT

       If enabled via the  "--report"  option,  bbproxy  will  send  a  status
       message about itself to the BBDISPLAY server once every 5 minutes.

       The status message includes the following information:

       Incoming messages
              The  total number of connections accepted from clients since the
              proxy started. The "(N msgs/second)" is the  average  number  of
              messages per second over the past 5 minutes.

       Outbound messages
              The  total  number of messages sent to the BBDISPLAY and BBPAGER
              servers. Note that this is probably smaller than the  number  of
              incoming  messages, since bbproxy merges messages before sending
              them.

       Incoming - Combo messages
              The number of "combo" messages received from a client.

       Incoming - Status messages
              The number of "status" messages received from a client.  bbproxy
              attempts  to  merge  these into "combo" messages.  The "Messages
              merged" is the number of "status" messages that were merged into
              a combo message, the "Resulting combos" is the number of "combo"
              messages that resulted from the merging.

       Incoming - Page messages
              The number of "page" messages received from a client.

       Incoming - Other messages
              The number of other messages  (data,  notes,  ack,  query,  ...)
              messages received from a client.

       Proxy ressources - Connection table size
              This is the number of connection table slots in the proxy.  This
              measures the number of simultaneously active requests  that  the
              proxy has handled, and so gives an idea about the peak number of
              clients that the proxy has handled simultaneously.

       Proxy ressources - Buffer space
              This is the number of KB memory allocated for network buffers.

       Timeout details - reading from client
              The number of messages dropped because reading the message  from
              the client timed out.

       Timeout details - connecting to server
              The  number  of  messages  dropped,  because a connection to the
              BBDISPLAY or BBPAGER server could not be established.

       Timeout details - sending to server
              The number of messages dropped because the communication to  the
              BBDISPLAY/BBPAGER  server  timed  out  after  a  connection  was
              established.

       Timeout details - recovered
              When a timeout happens while sending the status message  to  the
              server,  bbproxy  will  attempt to recover the message and retry
              sending it to the server after  waiting  a  few  seconds.   This
              number  is  the  number  of messages that were recovered, and so
              were not lost.

       Timeout details - reading from server
              The number of response messages that timed out while  attempting
              to  read  them  from  the  server. Note that this applies to the
              "config" and "query" messages  only,  since  all  other  message
              types do not get any response from the servers.

       Timeout details - sending to client
              The  number of response messages that timed out while attempting
              to send them to the  client.  Note  that  this  applies  to  the
              "config"  and  "query"  messages  only,  since all other message
              types do not get any response from the servers.

       Average queue time
              The average time  it  took  the  proxy  to  process  a  message,
              calculated  from the messages that have passed through the proxy
              during the past 5 minutes. This  number  is  computed  from  the
              messages  that  actually end up establishing a connection to the
              BBDISPLAY or BBPAGER server,  i.e.  status  messages  that  were
              combined into combo-messages do not go into the calculation - if
              they did, it would reduce the average time, since it  is  faster
              to merge messages than send them out over the network.

       If you think the numbers do not add up, here is how they relate.

       The  "Incoming  messages"  should  be equal to the sum of the "Incoming
       Combo/Status/Page/Other messages", or slightly more because messages in
       transit are not included in the per-type message counts.

       The  "Outbound  messages"  should  be  equal  to  sum  of the "Incoming
       Combo/Page/Other messages", plus the  "Resulting  combos"  count,  plus
       "Incoming  Status messages" minus "Messages merged" (this latter number
       is the number of status messages that were NOT merged into combos,  but
       sent  directly).   The  "Outbound  messages" may be slightly lower than
       that, because messages in transit are not  included  in  the  "Outbound
       messages" count until they have been fully sent.

SIGNALS

       SIGHUP Re-opens the logfile, e.g. after it has been rotated.

       SIGTERM
              Shut down the proxy.

       SIGUSR1
              Toggles logging of individual messages.

SEE ALSO

       bb(1), bbd(1), hobbit(7)