EMDIS::ECS - ECS utility module
use vars qw($ECS $ECS_CFG $ECS_NODE_TBL); use EMDIS::ECS; $err = EMDIS::ECS::load_config("ecs.cfg"); die "Unable to initialize ECS: $err\n" if $err; ECS::log_error("This is an error."); $err = EMDIS::ECS::send_admin_email("Something happened.\n", "Here are details.\n"); ECS::log_error("error sending admin email: $err") if $err; $err = EMDIS::ECS::send_ecsmsg_email('UX', '', "msg_type=READY\n", "# comment\n"); ECS::log_error("error sending ECS message: $err") if $err;
This module contains a bunch of miscellaneous ECS related subroutines. However, most of the documentation found here pertains to the Perl ECS implementation in general, not those specific subroutines.
This Perl implementation of the EMDIS Communication System (ECS), herein referred to as "Perl-ECS", is generally compatible with the ECS specification published by the ZKRD, though it differs from the specification in some of its implementation details. A PDF document containing the original ECS specification is available from the ZKRD web site (see http://www.zkrd.de/).
Before Perl-ECS can be used, a number of pre-requisites must be satisfied.
Install Perl, preferably version 5.6.1 or higher. Then install the EMDIS::ECS package. (Presumably already done if you're reading this documentation online.)
Acquire an email account to be used by the ECS system. Perl-ECS uses SMTP to send outbound mail, so a SMTP server will need to be available for this purpose.
To read incoming email, Perl-ECS can use IMAP protocol, POP3 protocol, or a DIRECTORY method. If IMAP or POP3 protocol is used, that service will also need to be available.
Install and configure PGP and/or GnuPG encryption software. Refer to http://www.pgp.com/, http://www.pgpi.org/, http://www.gnupg.org/, and http://www.philzimmermann.com/ for more information on the topic of PGP and related software.
Once the above prerequisites are in place, it's time to configure your ECS system. Create a directory to hold the ECS data files and then run the ecs_setup program to help create a basic configuration file. The ECS configuration file can also be created and edited using a regular text editor.
The NODE_TBL used by Perl-ECS contains several additional fields not described in the ECS specification. See below for descriptions of NODE_TBL fields; the names of added fields are shown emphasized. The ecstool program provides commands to manipulate the NODE_TBL.
The highest sequence number acknowledged by this node.
The email address of this node.
The PGP or GnuPG userid of this ECS node.
Email address of administrator for this node.
Indicates whether meta-messages to/from this node should be encrypted ("true" or "false").
ID of secret key to be used for encrypted messages to/from this node. For this node only, overrides the ECS configuration file's GPG_KEYID or PGP_KEYID.
Passphrase for encr_out_keyid. For this node only, overrides the ECS configuration file's GPG_PASSPHRASE or PGP_PASSPHRASE.
Identifies the PGP or GnuPG signature for this node.
The type of encryption used by this node. Currently supported encryption types are "PGP2", "PGP2-verify", "OpenPGP", and "OpenPGP-verify" ("verify" indicates messages from the node are cryptographically signed and the signature should be verified).
The sequence number of the last message accepted from this node.
The sequence number of the last message from this node for which a MSG_ACK has been sent.
Date and time when the last message from this node was accepted.
Date and time when local ECS administrator was notified of communication loss with this node.
Date and time when the last message from this node was received.
Maximum message part size, in bytes, for this node. Defaults to MSG_PART_SIZE_DFLT from ECS config file if not specified or zero. Refer to the EMDISCORD email parts RFC (RFC-20091021-EmailParts.pdf) for additional information about message parts.
The ECS node name. (Primary key)
Indicates whether processing is currently disabled for this node (YES or NO).
The sequence number of the last message sent to this node.
Name of first file in processing queue. The filename shows the date and time when the file was retrieved from the email inbox. This field is automatically updated by the ecs_scan_mail program, once per T_SCN interval.
Minimum message seq_num of "early" message in processing queue. This value is updated only when a gap in message seq_num values is encountered. During message processing, if the "early" message situation persists longer than the number of seconds specified by the T_RESEND_DELAY configuration parameter and q_gap_seq does not change during this time period, the ecs_scan_mail program will automatically generate a batch of RE_SEND requests.
Date and time when q_gap_seq value was observed. This value is used to compute whether the T_RESEND_DELAY time interval has elapsed.
Maximum message seq_num in processing queue. This field is automatically updated by the ecs_scan_mail program, once per T_SCN interval.
Minimum message seq_num in processing queue. This field is automatically updated by the ecs_scan_mail program, once per T_SCN interval.
Number of messages in processing queue. This field is automatically updated by the ecs_scan_mail program, once per T_SCN interval.
File containing message currently being processed. For THIS_NODE only, this field is automatically updated by the ecs_scan_mail program during message processing.
Node id for message currently being processed. For THIS_NODE only, this field is automatically updated by the ecs_scan_mail program during message processing.
Sequence number of message currently being processed. For THIS_NODE only, this field is automatically updated by the ecs_scan_mail program during message processing.
Indicates whether READY meta-messages sent to this node will include last_recv_num and last_sent_num values (YES or NO).
A few notes regarding differences between Perl-ECS and the ECS specification.
Incoming messages are processed one at a time, with a processing time limit. Because of this, Perl-ECS is not susceptible to "fork bomb" problems that could occur when many messages are received in a short period of time.
There is no MSG_TBL to track "early" messages. Instead, the ecs_scan_mail program performs a brute force analysis of the mboxes/store directory once during each T_SCN interval.
If a gap in message seq_num values for a given node is encountered, and the lowest incoming message seq_num for that node has not changed for T_RESEND_DELAY seconds, the ecs_scan_mail program automatically issues a batch of up to 100 RE_SEND requests. Because missing email messages may indicate the existence of unusual problems, the ecs_scan_mail program also sends email to notify the ECS administrator when this happens.
To send email, Perl-ECS requires a SMTP server. Likewise, to read email, it requires a POP3 or IMAP server. It does not use mailx or other system specific software.
The NODE_TBL contains several additional fields: encr_meta, encr_sig, encr_typ, last_in_adm. See the above NODE_TBL section for details.
Incoming FML messages are archived in the mboxes/in_fml subdirectory.
The ecstool program has been given additional capabilities. For details, refer to the ecstool documentation (e.g. "perldoc ecstool" or "man ecstool").
A significant number of new settings have been added to the ECS configuration file. For details, refer to the EMDIS::ECS::Config documentation (e.g. "perldoc EMDIS::ECS::Config" or "man EMDIS::ECS::Config"). The ecs_setup program is designed to help in the creation of a basic ECS configuration file.
The files in ECS_DAT_DIR that contain the PIDs for the ecs_chk_com and ecs_scan_mail daemons are ecs_chk_com.pid and ecs_scan_mail.pid, respectively.
The ecs_chk_com and ecs_scan_mail daemons do not share common log and err files.
The ECS daemons do not check for the presence of an ecs_off.lck file.
The ecs_scan_mail daemon sets ADAPTER_CMD and ECS_DRP_DIR environment variables during execution of the MSG_PROC command. The default MSG_PROC script provided with Perl-ECS ("ecs_proc_msg") executes the command specified by ADAPTER_CMD when processing a message. ECS_DRP_DIR specifies the location of the ECS_DAT_DIR/maildrop directory.
The "maildrop" directory holds outbound messages generated by the MSG_PROC, ADAPTER_CMD, or "ecstool --maildrop" commands. During each T_SCN interval, after messages in the mboxes/store directory have been processed, FML files found in the maildrop directory are automatically sent to the appropriate destination, based on the values of the HUB_SND and HUB_RCV fields. (However, the maildrop FML parser is currently unable to process HUB_SND and HUB_RCV values formatted using /FIELDS or /CONST.)
Any incoming non-ECS messages are passed to ADM_ADDR.
There is no mboxes/active subdirectory. This directory is not needed when reading mail from a POP3 or IMAP inbox.
Scripts or programs named ecs, ecs_send_msg, and ecs_resend_req are not provided.
Possibly.
EMDIS::ECS::Config, EMDIS::ECS::FileBackedMessage, EMDIS::ECS::LockedHash, EMDIS::ECS::Message, ecs_chk_com, ecs_proc_meta, ecs_proc_msg, ecs_scan_mail, ecs_setup, ecstool
Neil Smeby <nsmeby@nmdp.org>
Joel Schneider <jschneid@nmdp.org> - modifications, refactoring, documentation, etc.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Copyright (C) 2002-2016, National Marrow Donor Program. All rights reserved.
See LICENSE file for license details.
ECS, the EMDIS Communication System, was originally designed and implemented by the ZKRD (http://www.zkrd.de/). This Perl implementation of ECS was developed by the National Marrow Donor Program (http://www.marrow.org/).
2004-03-12 Canadian Blood Services - Tony Wai Added MS Windows support for Windows 2000 and Windows XP Added "DIRECTORY" inBox Protocol. This can interface with any mail system that can output the new messages to text files.
2007-08-01 ZKRD - emdisadm@zkrd.de Added new error report management using the new variable MAIL_LEVEL. All email to admin statements are removed. In relation to the error code ECS.pm will send an email to admin or not. Bugfix for the regular expression in sub read_ecs_message_id(): The regular expression now ignores spam tags in the subject line. Hold lock in send_ecsmsg_email until msg. is successfully send.
To install EMDIS::ECS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm EMDIS::ECS
CPAN shell
perl -MCPAN -e shell install EMDIS::ECS
For more information on module installation, please visit the detailed CPAN module installation guide.