• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

orb2orb - copy data from one or more input orbservers to one or more output orbservers

SYNOPSIS

CURRENT SYNTAX:

orb2orb [-qvx]
            [-m match]
            [-p pf]
            [-r reject]
            [-S statefile]
            [-t targetname]
            [[orbtag orbname] ...] [starttime [period|end-time]]

LEGACY SYNTAX:

orb2orb [-qvx]
            [-m match]
            [-p pf]
            [-r reject]
            [-S statefile]
            [-t targetname]
            orbin orbout [starttime [period|end-time]]

DESCRIPTION

The orb2orb program transfers data packets from one or more input orbservers to one or more output orbservers. In the CURRENT command-line syntax, these orbservers are specified on the command-line via orbtags, which are explained further below. A starttime may optionally be specified on the command-line. Following the starttime, either a period or an end-time may be specified. A period is most conveniently specified as hh:mm, or perhaps hh:mm:ss (in truth, the period is parsed through the str2epoch(3) function, so any format acceptable to that function will work). The starttime and end-time may be specified in any of the formats understood by epoch(1). Another alternative to a specific endtime is the word last, which tells orb2orb to copy to the last packet in the ring buffer and then stop. Specifying last causes orb2orb to copy until the packet it copies corresponds to the packet the orbserver reports as the last packet in the orb when the orb2orb instance was started.

Legacy Mode

orb2orb supports both CURRENT and LEGACY modes for command-line syntax and parameter-file contents. When used with the CURRENT command-line syntax, shown above, orb2orb requires the CURRENT-format parameter-file with connections table etc. as described below in the PARAMETER FILE section. The orb2orb program is also backwards compatible with the command-line syntax of orb2orb. When orb2orb is launched with a command-line matching the LEGACY syntax, the parameter-file is also assumed to be in the the LEGACY format used by orb2orb. For further information on the LEGACY command-line and parameter-file format, see the man-page orb2orb_dep(1).

OPTIONS

FILES

orb2orb uses the statefile, if one is specified with the -S option, to track times and packet id's for the last packet acquired from each orbserver.

COMMANDS

The orb2orb supports orb-based commands via the mechanism described in dlcmd(1). As described in that man-page, dlcmd(1) may be used to issue commands to orb2orb that are read from an orbserver by orb2orb (conventionally with the orbtag of cmdorb). After orb2orb takes action on a given command, depending on the contents of the incoming command it optionally writes a response packet back to the command orbserver indicating the disposition of the completed command. In the parlance of dlcmd(1), the dltype should be set to orb; the target corresponds to the target name of the orb2orb instance (defaulting to orb2orb if not specified); and the dlname corresponds to the connection task or tasks to be affected by the command. All changes made via orb2orb commands are transient, persisting only until changed by other commands or until the current process instance of the orb2orb executable is terminated. No updates are made to the orb2orb parameter-file to reflect configuration changes invoked by orb commands.

Available Commands

PARAMETER FILE

Parameter Descriptions

Parameter-file Example


connections &Tbl{
      &Arr{
            name                    reader_main
            read_from_orbtag        inputorb
      }
      &Arr{
            name                    writer_main
            write_to_orbtag         outputorb
      }
}

connections_defaults &Arr{
      read &Arr{
            read_from_orbname
            read_from_orbtag
            write_to_queue          mainq
            starttime
            endtime
            too_old
            too_new
            check_unstuff           true
            suppress_unstuff_errors true
      }
      write &Arr{
            read_from_queue         mainq
            write_to_orbname
            write_to_orbtag
            max_queue               10000
            acknowledge             no
      }
      shared &Arr{
            run                     true
            match
            reject
            verbose                 notify
      }
}

connections_special &Arr{
      status &Arr{
            run                     true
            write_to_queue          mainq
            verbose                 notify
      }
      logs &Arr{
            write_to_queue          mainq
            verbose                 notify
      }
      commands &Arr{
            run                     true
            orbtag                  inputorb
            verbose                 notify
      }
      state &Arr{
            verbose                 notify
      }
}

time_intervals_sec &Arr{
      pfstatusreport                2
      internal_timeout              1
      shutdown_grace_period         15
      datarate_interval             60.0
      thruput_interval              120.0
      retain_unused_stateinfo       604800     # 604800 sec = 1 week
}

Parameter-file Connections Table Example: Multiple dataloggers

If a single orb2orb instance connects to multiple dataloggers by specifying an individual connection for each datalogger directly in the parameter-file, the connections table of the parameter file may look something like this:

connections &Tbl{
      &Arr{
            name                    reader_KCAN
            read_from_orbname       KCAN.example.com:9500
      }
      &Arr{
            name                    reader_KACQ
            read_from_orbname       KACQ.example.com:9500
      }
      &Arr{
            name                    reader_KALD
            read_from_orbname       KALD.example.com:9500
            run                     false               # Turn this station off for the moment
      }
      &Arr{
            name                    reader_KAMT
            read_from_orbname       KAMT.example.com:9500
      }
      ....
      ....
}

EXAMPLE


% orb2orb -v inputorb bbarray.ucsd.edu:gsn outputorb :

% dlcmd :gsn orb2orb orb - task reader_main pause

orb2orb:0 &Arr{
command     task reader_main pause
disposition done
sequence    .*_snowmass.brtt.com_3239_0
sequence_target   snowmass_2439_0
target      orb2orb
thostname   snowmass
tip
tpid  2439
tusername   kent
type  orb
}

% dlcmd :gsn orb2orb orb - task reader_main continue

orb2orb:0 &Arr{
command     task reader_main continue
disposition done
sequence    .*_snowmass.brtt.com_3574_0
sequence_target   snowmass_2439_1
target      orb2orb
thostname   snowmass
tip
tpid  2439
tusername   kent
type  orb
}

% dlcmd :gsn orb2orb orb - program quit

orb2orb:0 &Arr{
command     program quit
disposition done
sequence    .*_snowmass.brtt.com_3860_0
sequence_target   snowmass_2439_2
target      orb2orb
thostname   snowmass
tip
tpid  2439
tusername   kent
type  orb
}

%

To read packets out of an forbserver(1) file as input:

% orb2orb inputorb ./packets_data.forb outputorb :

DIAGNOSTICS

Many diagnostics are available either as output to stderr, and/or as /log packets put on an orbserver(1).

SEE ALSO

orb2orb_dep(1), dlmon(1), pmtmanagedfifo(3)

BUGS AND CAVEATS

Due to complexities with proper statefile tracking in the current version of orb2orb, the setting of auto for the per-connection name parameter is no longer allowed. All connections must be given a unique name in the parameter-file. If a statefile is specified and also present, orb2orb ignores any configured starttime. The starttime parameter is honored if there is no statefile specified, or if one is specified but not present. If a statefile is specified and reconnection discovers that the orbserver has already lapped past the data timestamp specified in the statefile, orb2orb attempts to restart acquisition at the oldest packet in the orbserver. The current version of orb2orb will do its best to use statefile information from previous versions of orb2orb, updating the state file to current format as orb2orb runs. Not all features of statefile and starttime management that are available for the current version command-line syntax are available when using legacy command-line syntax. Going forward, not all new features added to orb2orb will be supported under the legacy command-line syntax. Please switch to the current version of the command-line syntax for the most up-to-date features and orb2orb behavior. When orb2orb is given an forbserver(1) file as input, all specified starttime information for that orb will be ignored. Instead, the named forbserver(1) file will be read from beginning to end, or until the endtime specified. Specifically, it is not necessary to specify on the command=line an endtime of last for an forbserver(1) file. The output of log-message packets to an orbserver(1) is limited to messages having Oorb::LogMsg::Severity(3) of very or below, in order to prevent self-amplifying message cascades. Also, not all shutdown-related messages are able to be echoed to an orbserver(1) due to chicken-and-egg problems. It is in principle possible to configure orb2orb such that a particular queue gets filled in by a read task (or packet-creation process such as the status-monitoring task), without that queue getting emptied by any corresponding write task. This can result in a growth in memory usage of the program, which should be avoided by proper configuration. The connections_special{logs} and connections_special{status} parameters were formerly named log_create and status_create. They have been renamed to align better with current and future expansions. When running in extremely verbose mode and above, the log files for orb2orb running under an rtexec(1)-based system can fill exceedingly quickly. While this is once again not recommended for operational use, if extremely verbose mode is needed for any length of time, it may be necessary to invoke an rtexec(1) cron procedure such as

cleanlogs   LOCAL   0,15,30,45   *  *  *  *   truncate_log -v -f -m 10000 -r logs/orb2orb

Per the rtexec(1) man-page, the above in the crontab table of rtexec.pf would limit the orb2orb process log to the order of 10 Megabytes.

AUTHOR

Kent Lindquist
Printer icon