Chapter 6. Configuration files

6.1 gcf-to-miniseed

The configuration file for the gcf-to-miniseed utility consists of three major components: general options, output options, and channel mapping. The format of the configuration file is an ASCII text file with one option per line. White-space and blank lines are ignored. Anything after a # symbol on a line is considered a comment.

Each line is either in the format

option = value

or

[section-header]

Quotes are not used in the file.

6.1.1 General options

These appear at the top of the file, before any section header. The available options are:

• corrupt_gcf_blocks: this can be discard (throw away invalid GCF blocks), data_quality (decode invalid data blocks and set the SEED data quality flags in the Mini-SEED record header), or warn (decode the invalid blocks, warn the user, but don't alter the output SEED).

• discard_byte_pipe: some digitisers have a “byte pipe” mode where bytes read on their serial input port (“Data In”) are stored in an opaque GCF block (channel name ending BP) and transmitted at regular intervals. If such blocks are detected, they are output in a similar manner to SOH data in Mini-SEED. Setting this option to true will discard these blocks; false will keep them.

6.1.2 Output options

These appear below a [miniseed] section header.

• record_size: the size of record as a power of two. Output record will consist of 2record_size bytes. This has a minimum value of 8 (256 bytes), a maximum value of 20 (1 048 576 bytes, or 1 MiB) and a default value, if unspecified, of 12 (4 096 bytes).

• endian: the endianness of the data. May be big or motorola for most-significant byte first, or little or intel for least-significant byte first. If omitted, the default is big endian.

• file_length: the length of output file segments, in seconds. One new file is created for each segment (depending on your naming scheme). This has a minimum of 10 seconds and a maximum of 86 400 seconds (one day). Data recorded on a leap second at 23:59:60 count as being at 23:59:59 for the purposes of determining the output segment.

• soh_length: the length of output file segments for ASCII SOH (state of health) data and byte pipes. If omitted, the value of file_length is used.

• output_filename: the template used to generate the name of each output file. See the following section for details. The template may specify a relative or an absolute path. If relative, files are created relative to the directory in which gcf-to-miniseed is run.

6.1.3 Channel mapping options

In manual mapping mode (and in auto mapping mode, if overrides are desired), each GCF block name must be mapped onto a SEED name. This is achieved with a section header consisting of the GCF name: [SYSID-STRID] followed by a single option called seedname which specifies the mapping. For example:

[SYSID-STRID]

seedname = STA.CHA.NET.LOC

[SYSID-STRID]

seedname = STA.CHA.NET

[SYSID-STRID]

seedname = STA.CHA

[SYSID-STRID]

seedname = STA.CHA..LOC

Following SEED 2.4 conventions, STA (the station code) must be 5 characters or less (upper-case A-Z and 0-9), CHA (the channel identifier) must be 3 characters or less (A-Z, 0-9), LOC (the location code) must be 2 characters or less (A-Z, 0-9), and NET (the network code) must be 2 characters or less (a-z, A-Z, 0-9). Either network code or location code may be omitted.

6.1.4 Output file-name options

Output files are created according to the scheme specified in the output_filename option of the [miniseed] section. This gives a template which is used to create the output filenames. If the template is static, all Mini-SEED records will be written to a single file. Otherwise, the following tokens within the file are replaced:

• %Y: 4-digit year

• %M: 2-digit month (1-12)

• %D: 2-digit day of month (1-31)

• %O: 3-digit day of year (1-366)

• %h: 2-digit hour (0-23), referring to start of segment

• %m: 2-digit minute (0-59), start of segment

• %s: 2-digit second (0-59), start of segment

• %i: GCF system ID

• %t: GCF stream ID

• %e: GCF serial number (stream ID less last two chars)

• %c: GCF component letter (usually Z,N,E,M)

• %p: sample rate (negative means seconds per sample)

• %S: SEED station name

• %C: SEED channel name

• %N: SEED network name

• %L: SEED location name

• %%: a literal % character

6.2 tcpserial

The configuration file for the tcpserial daemon specifies its operating mode and IP parameters. The format of the configuration file is an ASCII text file with one option per line. White-space and blank lines are ignored. Anything after a # symbol on a line is considered a comment.

Each line is either in the format

option = value

or

[section-header]

Quotes are not used in the file.

6.2.1 Simple server mode options

The simple server mode is specified by including

mode = simple_server

The available options are:

• bind: a list of space-separated ports to bind to. Each port is specified as either SERVICE or ADDR,SERVICE. SERVICE is a service name (from /etc/services) or a TCP port number between 1 and 65535. If specified, ADDR is the host-name or IP address to bind to. If omitted, the daemon listens on all configured addresses. Multiple addresses/ports may be given, but only one client can be connected at a time.

• ip_filter: if specified, this allows some simple checking of the client source address. The argument is a set of comma-separated addresses. Each address is specified as POLICY(ADDRESS) or POLICY(ADDRESS/NET). The POLICY must either be accept or reject. The ADDRESS is an IP address or host-name. If specified, NET is the number of bits that must match (CIDR form). Connections from unknown addresses are rejected.

6.2.2 Simple client mode options

The simple client mode is specified by including

mode = simple_client

The only available option is:

• server: the remote server to connect to. Specified as HOST,SERVICE where HOST is an IP address or host-name and SERVICE is a service name from /etc/services or a TCP port number.

6.3 cd11-test-recv

The configuration file for the CD11 test receiver specifies its operating mode and IP parameters. The format of the configuration file is an ASCII text file with one option per line. White-space and blank lines are ignored. Anything after a # symbol on a line is considered a comment.

Each line is either in the formatted

option = value

or

[section-header]

Quotes are not used in the file.

6.3.1 Logging options

Unless overridden with the -s command-line switch, cd11-test-recv will, by default, log to the system log (syslog). By default, the application will use a syslog tag based on the name of its configuration file, e.g. ntp-to-nmea[test]. This can be overridden by changing the log_name variable.

The level of messages which can be logged is set by the log_level variable which may take values LOG_DEBUG (which includes debugging messages, of which there are many), LOG_INFO (information and above levels), LOG_NOTICE (important notices and above), LOG_WARNING (warnings and above). The default is LOG_DEBUG, which would be sensible to change for a production system.

It is also possible to log to a file by setting the option log_file with a value which is a valid file-name.

6.3.2 Network configuration options

CD1.1 only works over TCP with IPv4 addressing. There is no UDP or IPv6 support. Unlike some CD1.1 receivers, the Güralp CD1.1 receiving code only requires a single TCP port to listen on; all connections come through this one port.

The address to listen on must be specified - both the IP address (or host-name) and the port number (or service name from /etc/services). This is done by setting the option bind_host, which can be set to 0.0.0.0 to specify listening on all interfaces (the most common situation) and bind_service. Port 8000 is a common choice for the port number for this.

Due to the connection establishment mechanism of CD1.1, it is also necessary to provide the external IP address and port number of the receiver, as it would be viewed by the sender. This is done using the options connect_host and connect_service. It is not possible to use 0.0.0.0 for connect_host; the correct, externally-visible address must be used.

6.3.3 CD1.1 configuration options

receiver_name is the name passed in frame headers. It must be 8-characters or fewer and must consist solely of numbers and/or upper-case letters.

station_type must be set to NDC (National Data Centre), IDC (International Data Centre), or IMS (International Monitoring System) as appropriate. It is passed in frame headers. This setting is not used by Güralp code, except for logging.

senders is a list of sender names, separated by spaces. Connections from senders will only be accepted if they are identified with a name from this list.

6.3.4 File and directory options

clientdb_dir is a directory in which frameset files are stored. These are used for persistence in recording received frames across daemon restarts. This should point to an initially-empty directory. It will be populated with files named after senders.

cert_dir is a directory in which certificates may be loaded. It is optional and is only required if signatures are being verified. It should point to a directory containing files named AUTH_KEY_ID.pem where AUTH_KEY_ID is the base-10 representation of the authentication key ID.

frame_log_dir is the directory in which the frame/subframe log files (.csv files) are written. It will be populated with .csv files named after the senders.

6.3.5 Sample configuration file

The example contents below can be copied and edited to ease configuration of your own instance.

receiver_name = TEST

station_type = NDC

bind_host = 0.0.0.0

bind_service = 8010

connect_host = 81.187.130.163

connect_service = 8010

clientdb_dir = /home/cd11user/CD1.1-testing/framesets

senders = EKA1 EAK2 A3175 TANTALUM A2113

log_file = /home/cd11user/CD1.1-testing/logs/server.log

log_level = LOG_INFO

cert_dir = /home/cd11user/CD1.1-testing/certs

frame_log_dir = /home/cd11user/CD1.1-testing/logs