ringserver - Generic packet ring buffer

(man page 2015/07/07)

Synopsis

ringserver [options] [configfile]

Description

ringserver is a TCP-based ring buffer designed for packetized streaming data. The primary implementation criteria are scalability and stability. The ring buffer is implemented as a FIFO with newly arriving packets pushing older packets out of the buffer. The ring packets are not format specific and may contain any type of data. All communications are performed via TCP interfaces. Data is available to clients using the SeedLink and DataLink protocols and submitted to the server using the DataLink protocol.

The server is configured either with options on the command line or by using a ringserver config file (or both). Only the most common options are available on the command line, all options are tunable via the config file. Detailed descriptions for each option are included in the example config file that accompanies the source code. Many options are dynamic, meaning that they can be changed while the server is running. In this case the server will recognize that the config file has changed and will re-read it's configuration. This is especially useful for updating access control lists, logging verbosity and other logging parameters.

In normal operation packet buffer contents are saved in files when the server is shut down making the server stateful across restarts. By default the packet buffer is managed as a memory-mapped file, it can optionally be maintained completely in system memory and only read and write the buffer contents on startup and shutdown (useful in environments where memory-mapping is not possible).

Client access is controlled using 3 IP address based lists: one list for specific IPs that must match, one list for specific IPs that are to be rejected and one for IPs that are allowed to send data to the server (write access). See Access Control for more details.

Transfer logs can optionally be written to track the transmission and reception of data packets to and from the server. This tracking is stream-based and identifies the number of packet bytes of each unique stream transfered to or from each client connection.

The slinktool(1) and dalitool(1) programs can be used to query the ringserver for various information via the SeedLink and DataLink interfaces respectively. The dalitool program was developed in parallel with ringserver and the DataLink protocol and is the recommended query tool for ringserver admins.

Options

-V

Print the program version and exit.

-h

Print the program help/usage and exit.

-H

Print an extended help/usage and exit.

-v

Be more verbose. This flag can be used multiple times ("-v -v" or "-vv") for more verbosity.

-I ServerID

Server ID reported to the clients. The value may be a quoted string containing spaces. The default value is "Ring Server".

-M maxclientsperIP

Maximum number of concurrently connected clients per IP address. This limit does not apply to addresses with write permission. There is no default maximum.

-m maxclients

Maximum number of concurrently connected clients. The default maximum is 600.

-Rd ringdir

Base directory for the server to store the packet buffer data files. This option must be specified on the command line or in the config file, there is no default.

-Rs bytes

Size of the packet buffer in bytes, default size is 1 GB. The size of the ring, in combination with the ring packet size, determine how much past data is available in the buffer. If the server is configured to memory-map the packet buffer files the maximum size of the ring is limited to how large a file the host system can support. If the server is configured to maintain the ring in system memory the size is limited to system memory.

-Rm maxID

Maximum ring packet ID used to uniquely identify a packet. Default is 16,777,215 which the maximum supported by the SeedLink protocol, if SeedLink is not being used it can be much higher.

-Rp packetsize

Maximum ring packet data size (not including packet buffer header), default is 512 bytes.

-NOMM

No memory-mapping, maintain the ring buffer in system memory only. On startup the ring buffer files will be read into memory and on shutdown the memory buffers will be written back to the files. This option might be useful in environments where memory-mapping of files is not possbile or is unreliable (e.g. NFS).

-DL port

Network port to listen for DataLink connections on, by default the server will not listen for DataLink connections. 16000.

-SL port

Network port to listen for SeedLink connections on, by default the server will not listen for SeedLink connections.

-T logdir

Transfer log file base directory, by default the server does not write transfer logs. If a directory is specified both transmission and reception logs will be written, these two logs can be toggled individually in the server config file.

-Ti hours

Transfer log writing interval in hours, default interval is 24 hours. The interval always starts at day boundaries, for example if the interval is set to 2 hours then the first interval in a given day will cover hours 0 through 2, the next 2 through 4, etc.

-Tp prefix

Transfer log file prefix, by default no prefix is added to the fixed section of the log file name.

-STDERR

Send all diagnostic output to stderr instead of stdout. This is useful in situations where logging output is captured by another program on stderr and to separate ringserver diagnostics from other output on the console.

-MSWRITE format

A special mode of ringserver is to write all Mini-SEED data records received via DataLink (ring packets ending with the /MSEED suffix) to a user defined directory and file structure. See Mini-SEED Archiving for more details.

-MSSCAN directory [suboptions]

A special mode of ringserver is to recursively scan a directory for files containing Mini-SEED formatted data records and insert them into the ring as packets with a /MSEED suffix. Optional suboptions control scanning behavior, the StateFile suboption is highly recommended. See Mini-SEED Scanning for more details.

-VOLATILE

Create a volatile (non-stateful) ring buffer, in other words do not read packet buffer contents from ring files on startup or write them on shutdown. This is useful in combination with the -MSWRITE option when no stateful buffer is needed.

Config File Parameters

All of the command line parameters have config file equivalents, below are the config file parameters which have no command line equivalents. Many of the config file parameters are dynamic, if they are changed the server will re-read it's configuration on the fly. See the detailed parameter descriptions in the documented example config file.

*AutoRecovery* [0|1] - Control autorecovery after corruption detection
*ResolveHostnames* [0|1] - Control reverse DNS lookups
*TimeWindowLimit* % - Control limit for time window searches
*TransferLogTX* [0|1] - Control writing of transmission log
*TransferLogRX* [0|1] - Control writing of reception log
*WriteIP* IP[/netmaks] - Add IP address(es) to write permission list
*LimitIP* IP[/netmaks] RegEx - Add IP address(es) to limit list
*MatchIP* IP[/netmaks] - Add IP address(es) to match list
*RejectIP* IP[/netmaks] - Add IP address(es) to reject list

Access Control

By default all clients are allowed to connect. Specific clients can be rejected using the RejectIP config parameter. If any MatchIP config parameters are specified only addresses that match one of the entries and are not rejected are allowed to connect.

By default all clients are allowed access to all streams in the buffer. Specific clients can be limited to subsets of streams using the LimitIP config parameter. This parameter takes a regular expression that is used to match stream IDs that the client(s) are allowed access to.

If no client addresses are granted write permission via WriteIP then the address 127.0.0.1 (local loopback) is granted write permission.

Seedlink Support

The SeedLink protocol only transmits 512-byte Mini-SEED data records. Therefore only 512-byte Mini-SEED packets with a '/MSEED' suffix on the stream ID will be exported via SeedLink if enabled.

This server supports the wildcarding of network and station codes during SeedLink negotiation using the '?' and '*' characters for single or multiple character matches respectively. Not all SeedLink clients support wildcarded network and station codes.

Mini-Seed Archiving

Using either the -MSWRITE command line option or the MSeedWrite config file parameter the server can be configured to write all Mini-SEED data records received via DataLink to a user defined directory and file structure. The archive format argument is expanded for each packet processed using the following flags:

  *n* : network code, white space removed
  *s* : station code, white space removed
  *l* : location code, white space removed
  *c* : channel code, white space removed
  *q* : record quality indicator (D,R,Q,M), single character
  *Y* : year, 4 digits
  *y* : year, 2 digits zero padded
  *j* : day of year, 3 digits zero padded
  *H* : hour, 2 digits zero padded
  *M* : minute, 2 digits zero padded
  *S* : second, 2 digits zero padded
  *F* : fractional seconds, 4 digits zero padded
  *D* : current year-day time stamp of the form YYYYDDD
  *L* : data record length in bytes
  *r* : sample rate (Hz) as a rounded integer
  *R* : sample rate (Hz) as a float with 6 digit precision
  *h* : host name of client submitting data
  *%* : the percent (%) character
  *#* : the number (#) character

The flags are prefaced with either the * or *# modifier. The * modifier indicates a defining flag while the *# indicates a non-defining flag. All received packets with the same set of defining flags will be saved to the same file. Non-defining flags will be expanded using the values in the first packet received for the resulting file name.

Time flags are based on the start time of the given packet.

Files are created with (permission) mode 666 and directories are created with mode 777. An operator of ringserver can control the final permissions of the files by adjusting the umask as desired.

Some preset archive layouts are available:

  *BUD*   : _%n/%s/%s.%n.%l.%c.%Y.%j_  (BUD layout)
  *CHAN*  : _%n.%s.%l.%c_  (channel)
  *QCHAN* : _%n.%s.%l.%c.%q_  (quality-channel-day)
  *CDAY*  : _%n.%s.%l.%c.%Y:%j:#H:#M:#S_  (channel-day)
  *SDAY*  : _%n.%s.%Y:%j_  (station-day)
  *HSDAY* : _%h/%n.%s.%Y:%j_  (host-station-day)

The preset archive layouts are used by prefixing a target directory with the preset identifier followed by an '@' character. For example:

BUD@/data/bud/

would write a BUD like structure in the /data/bud/ directory.

Other example:

/archive/%n/%s/%n.%s.%l.%c.%Y.%j

would be expanded to day length files named something like:

/archive/IU/ANMO/IU.ANMO..BHE.2003.055

Using non-defining flags the format string:

/data/%n.%s.%Y.%j.%H:#M:#S.miniseed

would be expanded to:

/data/IU.ANMO.2003.044.14:17:54.miniseed

resulting in hour length files because the minute and second are specified with the non-defining modifier. The minute and second fields are from the first packet in the file.

Mini-Seed Scanning

Using either the -MSSCAN command line option or the MSeedScan config file parameter the server can be configured to recursively scan a directory for files containing Mini-SEED data records and insert them into the ring. Intended for real-time data re-distribution files are continuously scanned, newly added records are inserted into the ring.

Sub-options can be used to control the scanning process. The sub-options are specified on the same line as the scan directory as key-value pairs separated by an equals '=' character and may not contain spaces (because they are separated by spaces). Do not use quotes for the values. The available sub-options are:

  *StateFile* : File to save scanning state through restarts
  *Match* : Regular expression to match file names
  *Reject* : Regular epression to reject file names
  *InitCurrentState* : Initialize scanning to current state
  *MaxRecurse* : Maximum recursion depth (default is no limit)

Except for special cases the StateFile option should always be specified, otherwise a restart of the server could re-read data records that it has already read.

If the InitCurrentState option is set to '*y*' the scanning will only read new data, effectively skipping all the data discovered during the first scan, under the following conditions:

1) No StateFile has been specified
2) StateFile has been specified but does not exist

The InitCurrentState option is useful to avoid reading all existing data when starting a server scanning an existing large dataset. It is also useful to reset the dataflow to current data after a lengthy downtime, simply remove the statefile(s) before starting the server.

To scan a data directory and save the scanning state to a StateFile configure the server with either a config file option or command line, respectively:

MSeedScan /data/miniseed/ StateFile=/opt/ringserver/scan.state

-MSScan "/data/miniseed/ StateFile=/opt/ringserver/scan.state"

To limit the scanning to file names matching a certain pattern use the Match option, e.g. files ending in ".mseed":

MSeedScan /data/miniseed/ StateFile=/data/scan.state Match=.\\.mseed$*

Author

Chad Trabant
IRIS Data Management Center