NAME

orbserver - orb ring buffer server

SYNOPSIS

orbserver [-p port] [-P prefix] [-s size] [-fFhkKr] [{-v|-vv}] pfname

DESCRIPTION

orbserver is an orb ring buffer server, configured according to the parameter file pfname. It listens either at the default port or a specified port number and starts new threads which service requests from each new connection. A connection may be one of two types: a read connection or a write connection. A write connection allows saving packets into the ring buffer. A read connection allows getting packets from the ring buffer, or getting other information (statistics) about the ring buffer and packets.

Note that if you are running multiple instances of orbserver, you must specify a unique port and a unique prefix (set of local file buffers) for each instance. The prefix is most conveniently specified on the command line using the -P option, but can also be handled in the parameter file, by providing a separate parameter file for each orbserver instance.

OPTIONS

• -f
  Cause the ring buffer files to be completely zero filled as they are created, before the orbserver allows connections. This can take a considerable amount of time for large buffers, but ensures that the buffer files have been completely allocated and should also minimize buffer file fragmentation. This option is now turned on automatically by default.
• -F
  Suppress zero-filling of ring buffers. This operation silently overrides -f if both are specified.
• -h
  stop after creating the ring buffer files.
• -k
  Don't reset the ring buffer, even if there is some inconsistency in the buffer. In this case, the orbserver quits without modifying the ring buffer when there is an inconsistency; this is primarily for debugging.
• -K
  Don't reset the ring buffer, and ignore the results of the verification tests. This is a debugging tool, and shouldn't be used in actual operation.
• -p port
  Use the specified port, instead of the default. The port name may be preceded by ':', to facilitate the use of $ORB inside an rtexec(1) parameter file. The default port is 6510.
• -P prefix
  override prefix specification inside parameter file
• -r
  reset the ring buffer, effectively clearing out the ring buffer before starting. This option requires confirmation.
• -s size
  specify ring buffer size on the command line instead of in parameter file
• -t
  throttle input streams when reap clients have large lag values; ignore stalled reap threads (where current pktid doesn't change between lag calculations).
• -v|-vv
  The server can be verbose at two levels. At the first level, it announces new connections. At the second level (-vv), it verbosely dumps queries and responses, but not packets.

FILES

orbserver creates and maintains several ring buffer files. The directory and initial portion of the names of these files are specified by the prefix parameter in the parameter file. The files include a buffer containing packets and indexes of packet id and source id.

These orb ring buffer files must be local to the machine where orbserver is running, not nfs mounted.

DYNAMIC CONTROLS

orbserver does not create a .dynamic_controls file. However, if the file .dynamic_controls is present, the following controls and variables may be modified or observed.

• throttle
  When this is set, the orbserver attempts to slow down incoming packets when any reaping thread is falling behind.
• verbose_orb_reconnection
  Show ORBRUP requests.
• catchup_rate
  multiplier which affects the target rate at which threads falling behind should catch up.
• performance_calculation_period
  The orbserver recalculates various performance statistics on a schedule which needs to be long enough to be somewhat stable, and not so short as to affect performance.
• percentage
  The statistics are averaged by adding the previous value * percentage + the current value * ( 1-percentage).
• maxlag
  
• stalled
  
• nreap
  
• delay
  These four controls are actually just showing the status of some numbers used for the throttle. maxlag is the maximum lag value for reaping threads. stalled is not used any more. nreap is the number of reaping threads. delay is the delay imposed by the orbserver between incoming packets when the orbserver is throttling.
• verbose_connections
  This flag controls whether the individual orbserver threads (client connections) show they start and stop.
• bnssnoop
  If set, all orb ip conversations are recorded in a file named after the BNS_SNOOP environment variable.

PARAMETER FILE

• ringsize
  This is the size in bytes of the buffer which holds the packet data; the number may optionally be followed by 'G', 'M', or 'k', indicating the units are Gbytes, Mbytes, or kbytes rather than bytes.
• minimum_packet_size
  The minimum packet size is used to calculate a size for the packet index, which contains the srcname, the packet size and offset into the packet buffer, and the packet time.
• maximum_packet_size
  The maximum_packet_size is used only to check that the ring buffer is big enough to hold several packets at once.
• concurrency
  This number is basically a hint to the operating system about how many system threads should be allocated to the orbserver. It's probably not necessary to ever change this.
• prefix
  This string is the prefix used to create the private data buffers for an orbserver. These buffers include a packet buffer, a packet index, a source index and a stash buffer. The orbserver prepends this string to fixed names corresponding to each private buffer. One might specify only a directory, e.g. orb/, or a directory and a leading prefix, e.g. orb/special_.
  
  If it is not already present, a directory is created. This directory must be on a locally mounted disk.
  
  If you are running multiple instances of orbserver, you need to specify a unique prefix for each instance.
• maximum_srcid
  The index of sources is of fixed size; this number affects the size of the source index when the orbserver is first initialized; thereafter, this number is ignored.
• initial_stash_size
  This is used as the initial size of the stash buffer. Thereafter, the stash buffer grows as necessary to contain all the current stash packets.
• valid_ip_addresses
  This is a list of ip addresses in dot format (e.g., 206.196.132.156) followed by a bit mask. During the initial connection process, orbserver determines the ip address of the system attempting to connect, and looks for a match in this list. If no match is found, the connection is not allowed.
  
  This list is reread at each connection attempt, so it can be edited while the orbserver is running to add new ip addresses or delete old ones. However, the list is checked only at the connection attempt; existing threads for a particular ip address are not terminated if their ip address is removed from the list.
  
  If the bit mask is followed by the keyword readonly, then connections from this ip address are read-only -- the connection does not allow data to be added to the ring buffer. Any attempt to do so causes the connection to be terminated and a log message to be generated.
  
  Alternatively, a regular expression may follow the bit-mask; then the connection is again read-only, and only packets with srcnames matching this regular expression are sent to the matching ip addresses.
• reject_ip_addresses
  Attempted connections from addresses which match entries in this list are rejected.
• time_index_spacing
  an index of pktid versus time is kept with this many seconds between entries. With the default one second, the first packet in the ring buffer after any particular second in the index is found with a simple table lookup.
• minimum_time_index_range
  
• maximum_time_index_range
  Normally, the size of the time index table is computed at start up based on the time range of packets already in the ring buffer. These parameters specify a minimum and maximum time range (in seconds) to allow in the time index.
• reject_message
  A message to be returned to client attempting to connect which is not in the valid_ip_addresses list. Leave this empty to continue the original behavior.
• log_packets
  log all reaped packets sent to these ip addresses (for debugging)
• statistics_interval
  if this is specified (non-blank), then some information is written to a log file orbserver_statistics at approximately this interval for each thread which has read or written packets. The interval may be plain seconds, or of the form HH:MM, e.g. 24:00. Because the threads are data-driven, the statistics are only printed after a thread reads or writes a packet. If the input to the orb is halted for some reason, the statistics are not printed on time. The statistics include a time. The counters are reset each time the statistics are printed.
• statistics_file
  Override the default output file for statistics orbserver_statistics; you might want these in the logs directory, for example.

EXAMPLE

command line

    % orbserver orbserver &

within rtexec

• Run two instances of orbserver. One instance, :usarray, uses a larger ring buffer. Two different parameter files are used, orbserver, and orbserverPROC. The only difference in the parameter files: ringsize is set to 1Gb for orbserverPROC.pf vs. 10Gb for orbserver.pf and prefix is orb/PROC- vs. orb/DATA-.

  
       orbserverDATA	orbserver  -p :usarray orbserver 
       orbserverPROC	orbserver  -p :proc    orbserverPROC 
  
  

SEE ALSO

orb(3)

BUGS AND CAVEATS

When an orbserver is first started and the buffers need to be created, it does not completely initialize the packet buffer, but instead seeks to the specified size and writes a byte. This tactic provides a very rapid initialization of large files. The downside to this approach is that the operating system does not actually allocate all of the file space. The space gets allocated as data gets written into the buffer files. If there is insufficient space on the disk to accommodate the packet buffer and the packet index and the source index, the orbserver does not fail immediately, but fails later (with a bus error or segmentation fault) when it attempts to save a packet onto an already full partition. Therefore, it is important to be sure there is adequate space on the partition for the packet buffer, and the packet index, and the source index. Alternatively, the -f option can be used to force zero filling of the entire buffer files at initialization which will insure that space is available at startup time.

The pktid by time index in memory is computed whenever orbserver is started, and thereafter updated whenever packets are added to the ring buffer. Because this index is fixed in size, under some conditions the index may not cover the entire time range of packets in the ring buffer. The index always covers the most recent packets, but when orbafter is called with a time before the beginning of the index, the orbserver is forced to do a linear search from the beginning of the ring buffer. This situation might occur when the input to the ring buffer has stopped for some time and is then restarted; the time range in the buffer might greatly exceed the fixed size of the table.

The source index is fixed in size; if the orbserver receives packets with srcnames which do not fit into the source index, these packets are dropped. The orbserver log shows this, but the client is not notified.

A connected program does not receive any notification of a problem if the orbserver rejects its packets because the source index is full, or its connection is read-only and it attempts to send packets to the ring buffer.

The stash buffer never shrinks in size, and the only way to remove unnecessary old stash packets is to restart the orbserver, deleting the stash buffer in the interim.

Prior to Antelope 5.0, two separate executables were available, orbserver and orbserver64. As later releases of Antelope are 64-bit, the separate orbserver64 executable has been removed.

AUTHOR

Daniel Quinlan
Boulder Real Time Technologies, Inc.