/ 
EMDIS-ECS-0.41
River stage zero No dependents
/ ecstool

NAME

ecstool - ECS administrative utility

SYNOPSIS

ecstool --config ecs.cfg

ecstool --add FR emdis@emdisf.fgm.fr 0xA772E879 PGP2

ecstool --archive 32

ecstool --decrypt mboxes/in/20030320_183247_1_0005_FYUh.msg

ecstool --export file.txt "|"

ecstool --get ES addr

ecstool --maildrop pat_upd.fml

ecstool --meta FR RE_SEND 12345

ecstool --modify FR emdis@emdis.fgm.fr 0xA772E879 PGP2

ecstool --overview

ecstool --prune ES 106732 248443

ecstool --send FR pat_upd.fml

ecstool --tweak FR addr emdis@emdisf.fgm.fr

ecstool --view

DESCRIPTION

This program performs a variety of ECS administrative functions.

OPTIONS

--config ecs_config_file

Specify the location of the ECS configuration file. By default, the program looks for the file specified by the ECS_CONFIG_FILE environment variable; if that environment variable is not set, it looks for a file named "ecs.cfg" in the current directory.

--add node addr addr_r encr_typ [encr_sig]

Add new ECS node to node_tbl. addr is the node's email address, addr_r identifies the node's PGP key (e.g. 0x44DEF332), encr_typ identifies the node's encryption type (e.g. PGP2, PGP2-verify, OpenPGP, or OpenPGP-verify), and encr_sig is the email address listed in the node's PGP or GnuPG key, if different from addr.

--archive [delete_threshold]

Create a tar archive of the current ECS status. Also, rotate the ecs_chk_com.log and ecs_scan_mail.log log files. If delete_threshold is specified, delete files greater than this number of days old before creating the archive.

--decrypt filename

Decrypt a message file.

--delete node

Delete ECS node from node_tbl.

--export <filename> [delimiter]

Exports the node_tbl to a <delimiter>separated (default "|") list. Hint for Unixshells: Wrap special characters like |, &, * in quotes, e.g. "|".

--get

View value of node properties in node_tbl for all nodes (default). If node specified, view information for that node only.

--help

Display short summary of usage information.

--maildrop [filename]

Send regular FML message. Reads from standard input if filename not specified. Instead of immediately sending the message, this command copies the message to the maildrop directory, for later processing by the ecs_scan_mail daemon (see also: --send).

--meta node msg_type [seq_num [seq2]]

Send meta-message to node. msg_type can be MSG_ACK, RE_SEND, or READY. If seq2 is specified for msg_type of MSG_ACK or RE_SEND, multiple meta-messages are sent, covering the range seq_num through seq2 (inclusive).

--modify node addr addr_r encr_typ [encr_sig]

Modify existing ECS node in node_tbl.

--nodedata import|export filename [node]

Import or export node_tbl data, using Data::Dumper format.

--overview

Print full overview of ECS configuration.

--prune node seq1 seq2

Prune input queue. Examine files in mboxes/store directory and move all messages for specified node, with sequence number between seq1 and seq2 (inclusive), to trash subdirectory.

--send [node] [filename]

Send regular FML message. Reads from standard input if filename not specified. If only one parameter specified, it is interpreted as a filename unless it happens to be a valid node id, in which case the parameter is treated as a node id and ecstool reads input from standard input. This command sends the message immediately (see also: --maildrop).

--tweak node property value

Tweak existing node in node_tbl. Use with caution.

--view [node]

View information in node_tbl (default). If node specified, view information for that node only.

EXAMPLES

Outgoing Message Processor

Using ecstool, an email account with procmail capability can be used as a processor for outgoing ECS messages.

This setup makes it possible for programs to send ECS messages without needing to directly interact with the ECS command line programs. Valid FML received by the email account can be sent out through ECS, and the ECS administrator is notified of any problems.

See below for example .forward and .procmailrc files.

Example .forward File
"|IFS=' ' && p=/usr/local/bin/procmail && test -f $p
  && exec $p -Yf- || exit 75 #ecsagent"
Example .procmailrc File
PATH=/bin:/usr/bin:/usr/local/bin
MAILDIR=$HOME/Mail
DEFAULT=$MAILDIR/mbox
LOGFILE=$MAILDIR/procmail.log
PERL5LIB=/home/emdis/ecs/lib
ECSADMIN=ecsadmin@transfuse.com.tm
ECSOUT=ecsout@transfuse.com.tm

# archive a copy of each incoming message
:0 c
archive/.

# detect mail loop (check for "X-Loop: $ECSOUT")
:0
* ^X-Loop: ecsout@transfuse.com.tm
/dev/null

# bounce "EMDIS Processing Error" directly to EMDIS admin
:0
* ^Subject:.*EMDIS Processing Error
| /usr/local/bin/formail -A "X-Loop: $ECSOUT" \
  -I "Reply-To: $ECSADMIN" | \
  $SENDMAIL $SENDMAILFLAGS $ECSADMIN

# attempt to send FML message, check ecstool exit code
:0 bw
| /home/emdis/ecs/script/ecstool \
  --config /home/emdis/ecs/ecs.cfg --maildrop

  # if above send command failed, notify EMDIS admin
  :0 e
  | /usr/local/bin/formail -A "X-Loop: $ECSOUT" \
    -I "Reply-To: $ECSADMIN" \
    -i 'Subject: EMDIS Send Error - see procmail.log' | \
    $SENDMAIL $SENDMAILFLAGS $ECSADMIN

RETURN VALUE

Returns a non-zero exit code if an error is encountered.

BUGS

Possibly.

NOTES

TBD.

SEE ALSO

EMDIS::ECS, ecs_chk_com, ecs_scan_mail, ecs_setup

AUTHOR

Joel Schneider <jschneid@nmdp.org>

COPYRIGHT AND LICENSE

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-2020 National Marrow Donor Program. All rights reserved.

See LICENSE file for license details.

HISTORY

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 environment variable ECS_CONFIG_FILE -> ecs.cfg. Added a export function to write the node_tbl delimiter separated (default '|') to a textfile. Added a get function which returns a single value from a node | all nodes. Added optional to_XX and from_XX directory support. Added a property check to the --tweak function.