NAME
ia2orb - Acquire data from Internet Accelerometers into Antelope orbserver
SYNOPSIS
ia2orb [-kvV] [-p pfname] [-s statefile] [-t target] [-c cmdorbname] orbname
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
The
ia2orb utility acquires data from Internet Accelerometer (IA)
dataloggers via the Internet Accelerometer relay server, placing the acquired
data onto the Antelope orbserver specified by
orbname. Files are converted
from the original miniseed into orb packets by the
Antelope
miniseed2orb(1) program, which is called automatically by
ia2orb.
The stations to be acquired are specified by the
ia_network array in the
parameter file. See the PARAMETER FILE section below for complete details. Each
station may have acquisition specified as
off,
on-demand, or
continuous. If a station is marked for
continuous acquisition,
all files are downloaded from the instrument as they become available. If a
station is marked for
on-demand acquisition, files are downloaded only upon
receipt of an acquisition command via the command-orb (usually put there by
the
iatrigger(1) or
iarequest(1) applications), and only for files matching the
requested point in time or time range for waveform data. The
ia2orb application
dynamically monitors its parameter file for changes to the
ia_network array,
so the
ia2orb application does not need to be stopped and restarted if
the status is changed for a given station.
OPTIONS
-
-c cmdorbname
This is the name of the orbserver containing acquisition commands for
ia2orb. Packets of type /pf/dlcm on this orbserver (with
the correct target name -- see the -t option below) will be
interpreted as instructions to acquire on-demand waveforms. If this
option is not specified, the command orbserver defaults to the name of the
data orbserver (orbname) given on the command line.
-
-k
Keep the original miniseed files downloaded from the IA (rather than
immediately erasing them after transfer to the orbserver).
-
-p pfname
Specify a parameter-file other than the default ia2orb.pf.
-
-s statefile
Specify a state-file. If this option is invoked, information is saved about the
last-acquired file from each station configured for continuous acquisition, such
that upon restarting, ia2orb will attempt to continue from where it
left off with each continuous station. (Although note that the reject_old_request_sec
parameter in the parameter file -- see below -- takes precedence, so if the statefile
is too far behind, data before reject_old_request_sec will not be requested).
-
-t target
This is the ia2orb instance name for commands delivered to the
command orb. If not specified, the default is ia2orb (i.e. the ia2orb program
will be looking for orb command packets of the name ia2orb/pf/dlcm on the command-orb).
-
-v
Be verbose.
-
-V
Be very verbose.
PARAMETER FILE
Parameter File Parameters
-
download_dir
This parameter specifies the directory into which miniseed files from the IAs
will be initially downloaded. (Unless the -k option is specified, the downloaded
files will be erased after they are uploaded to the orbserver).
-
ia_network
This array specifies all available stations in the Internet Accelerometer Network.
If a station does not appear in this list, it will not be acquired. There should be
one line per station in this table. Seven whitespace-separated values appear on each line. The first
is the name of the station, which must be unique. The second and third items are the
network name and grid name for the station, respectively. The fourth and fifth elements
give the relay server IP address and port number to use to connect to the station, respectively.
The sixth element is a boolean value indicating whether to byte-swap the time-correction value in the
acquired miniseed files from this station (accounting for a bug in some versions of the IA
firmware). The final element indicates the acquisition mode for this station. If this value is
continuous, continuous data are acquired from the given station. If on-demand, data are acquired
only in response to commands received by ia2orb via the orbserver. If this value is off,
no data are acquired from this station.
-
ia_user
This parameter gives the *nix username with which to connect to the
IAs through the relay server (the named user should exist on each
IA. It's not a requirement, nor standard, that the same user exist on the
relay server itself).
-
max_rangerequest_sec
The ia2orb program allows time-ranges of waveform data to be requested
(via command packets placed on the command-orb) from all stations configured in
on-demand acquisition mode (in the ia_network
parameter-file array). The max_rangerequest_sec parameter
specifies the maximum time-range of data, in seconds, that may be
requested from on-demand stations via the acqrange command to ia2orb. Requests for
time-spans of waveform data exceeding this length are summarily rejected by ia2orb.
-
relay_server_ip
This is the Internet address of the Internet Accelerometer relay server,
in dotted decimal notation. This parameter is not read directly by ia2orb,
rather it is a formatting convenience within the ia2orb.pf parameter file. The
relay_server_ip parameter may be used as a plain reference (see the man-page
pf(5) for more information on plain references) to fill in the rows of the ia_network
array, as demonstrated in the Parameter File Example below.
-
reject_future_data_sec
This parameter specifies the number of seconds into the future (as judged
by the system clock) beyond which data with future timestamps will be
rejected rather than acquired onto the orbserver. If reject_future_data_sec is less than 0,
all data are allowed.
-
reject_old_request_sec
This parameter specifies the number of seconds into the past beyond which data requests
will be ignored by ia2orb, whether coming from command-orb requests or from
state-file notes. If reject_future_data_sec is set to 0, no filtering is performed.
-
scp
This is the name of the scp(1) executable invoked by ia2orb, which can be just scp
if available on the local path (otherwise an absolute path should be specified).
-
ssh
This is the name of the ssh(1) executable invoked by ia2orb, which can be just ssh
if available on the local path (otherwise an absolute path should be specified).
Parameter File Example
ssh ssh
scp scp
download_dir /tmp
reject_future_data_sec 86400
reject_old_request_sec 129600
max_rangerequest_sec 3600
ia_user seismology
relay_server_ip 127.0.0.1
ia_network &Arr{
#
#sta net grid relay_server_ip relay_port byteswap_timecorr acquisition
#
PGC01 CN NA &relay_server_ip 99999 yes continuous
}
EXAMPLE
The ia2orb program may be run from the command line in a shell with
an ssh authentication agent, for example as follows:
% ssh-agent $SHELL
% ssh-add ~/.ssh/id_iauser
Passphrase:
% ia2orb -v ':@'
The following example shows how to trigger the acquisition of a segment of
data across the network for a given time, by putting a command packet on the
orbserver for the running ia2orb instance using the default target name
of ia2orb:
%cat mycmd.pf
command acqnet
time 1177721659.872
%
% pf2orb -s ia2orb -p dlcm mycmd :
%
SEE ALSO
iarequest(1), iatrigger(1), orbserver(1), miniseed2orb(1), ssh(5)
BUGS AND CAVEATS
ia2orb is strongly bound to the current naming convention and
timestamping patterns for files on the IA dataloggers. Changes to these
conventions will invalidate data-acquisition assumptions made in the
ia2orb code.
ia2orb presumes the IA is configured to return time-series data in
counts, not in physical units.
ia2orb presumes the account and shell under which it runs are already
authenticated for the ssh connections to the relay server. As a guideline
only, one way to accomplish this when running from an interactive environment
is by configuring an ssh agent:
% ssh-agent $SHELL
% ssh-add ./my_private_ssh_key_file
Passphrase:
%
The above example is only a guide to further exploration. The authentication
mechanisms for running
ia2orb (specifically, for running it continuously and
in an automated sense under the Antelope real-time system) will have to be
constructed to match the security policies of the site at which
ia2orb
is run. The intent here is to have the security engineering for the user's ssh
connectivity be completely distinct from the internal engineering of the
ia2orb program. For a few introductory suggestions on setting up password-less
ssh logins, see the man-page
ssh(5). For further information, consider referring to the
book
SSH, the Secure Shell: The Definitive Guide by Daniel J. Barrett,
Richard E. Silverman, and Robert G. Byrnes, O'Reilly publications, 2005.
ia2orb is currently set up to use only one relay server per station.
In principle it would be possible to expand it to use multiple relay servers,
falling back to second or third relay servers on failure of the first.
The
byteswap_timecorr capability was written as a workaround to a bug
in the Internet Accelerometer acquisition code at the time of writing. It is no
longer necessary to enable this for all instruments.
The -k option keeps the original files downloaded from the IA. However,
if the
byteswap_msd_timecorr parameter is set, the byte-swapping is
done in place on the files, so the files in the
download_dir will
be not quite identical to those on the IA itself.
ia2orb will not repeatedly attempt to retrieve a given file from the IA if
attempts to get that file are at first unsuccessful. The one exception to this is that
if the file to be acquired is for a station in
on-demand mode, if the failure
to acquire is due simply to
scp being unable to find or retrieve the file, and if the
request time is within one
IA block-size of the system-clock time, the relevant thread will
estimate an amount of time to sleep for that station, then re-post the request. This will hold off
requests for earlier data from the same station, however that data will still be requested after the
sleep cycle elapses.
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software