/** Enterprise Control Configuration and Logging Copyright (C) 2013 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Date: April 2013 Originally developed from 1996 to 2013 by Brainstorm, and donated to the FSF. This file is part of the GNUstep project. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA.

The index below lists the major components of the ECCL documentation.

Enterprise Control Configuration and Logging

Classes and tools for building and administering 24*7 server processes for large scale software systems.

The Control command line tool

Based around the [EcControl] class, this server process provides a central command/control point and acts as the SNMP agent for integration of a cluster of Objective-C based processes.

On startup, (or configuration change) the configuration dictionary from Control.plist (plus any included files) is written to /tmp/Control.cnf to provide a record of the latest config.

Periodically, the file /tmp/Control.alive is updated to indicate that the process is still running correctly. If the user default string ControlVersion is defined, it is written to one line of this file and in any case a timestamp is written.

If the EcControlKey NSUserDefault (32 hex digits) is set when the Control server is started, it must also be set to the same value in Control.plist, and on startup the Control server then requires manual entry of a key from the terminal (and makes the string entered (leading and trailing white space stripped) available as EcControlKey in the configuration information it gives to other processes.
This for instance allows all processes in a cluster to use a single encryption key never stored on disk.
The value of EcControlKey in Control.plist must be the MD5 hash of the value entered as the master key, otherwise the Control server will log a warning and shut down.
For purposes of automated testing only, Control.plist may contain the master key (64 hex digits) in EcControlKeyTest. In this case EcControlKey need not be defined as an NSUserDefault (because the Control server does not need to read the master key from the terminal).

The Command command line tool

Based around the [EcCommand] class, this server process provides the configuration/logging/launch facilities for all processes on a single machine. It obtains centralised configuration from the Control server and sends logging, alerts and alarms to that server.

The Console command line tool

Based around the [EcConsole] class, this process provides an interactive command-line based interface for controlling the entire system via the Control server.
It may also be used in a non-interactive mode to send commands to any process and wait for responses. The non-interactive mode is designed to provide a variety of exist status for use in scripting. In non-interactive mode the tool uses the following additional command-line-arguments/user-default-keys and/or environment variables:

User (or the ConsoleUser environment variable) specifies the user for whom the tool is performing an action.
Pass (or the ConsolePass environment variable) specifies the password for the user login to the Control server.
Line (or the ConsoleLine environment variable) specifies the command line to be used (as if typed in interactively). If the command line is sent, the process exit status is 0, but if a failure occurs the status is 1 (except as noted below).
Wait (or the ConsoleWait environment variable) specifies the number of seconds to wait for a Want/Fail pattern to be matched. If this timeout occurs, the process exit status is 2.
Want (or the ConsoleWant environment variable) specifies the regular expression to match a single message to the Console process. If this response is matched the process exit status is 0.
Fail (or the ConsoleFail environment variable) specifies the regular expression to match a single message to the Console process. If this response is matched, the process exit status is 3.
While waiting for a pattern to be matched, any messages received by the Console process are provided as output (to STDOUT).
Quiet (or the ConsoleQuiet environment variable) is a boolean which, if true, will suppress any output while waiting for a pattern to be matched.
If the Control server cannot be contacted, the process exit status is 10.
If the Control server actively refuses the login, the exit status is 11.
NB. Command line arguments take precedence over environment variables even if the command line argument is an empty string.
A couple of extra variables alter the format of output as follows:
Mark (or the ConsoleMark environment variable) can be set to YES to specify that each message is marked with a consistent start and end saying where the message was from.
Prompt (or the ConsolePrompt environment variable) can be set to NO to suppress the normal prompt line at the end of each message.
The AlarmTool command line tool

The AlarmTool command line tool provides a mechanism to raise and clear alarms (using the ECCL alarm system) from a process which is not itsself ECCL enabled (ie not built using the ECCL classes).
You may use this to generate logging from shell scripts or from Java servlets etc.

The tool requires at least four (usually six) arguments:
'-Cause NN' the probable cause of the alarm (type of problem).
'-Component NN' the component which raised the alarm.
'-Problem NN' the specific problem which raised the alarm.
'-Process NN' the name of the process which raised the alarm.
'-Repair NN' a proposed repair action to fix the issue.
'-Severity NN' the severity of the problem (defaults to 'cleared', in which case the Repair action is not required).

The LogTool command line tool

The LogTool command line tool provides a mechanism to log various types of messages (using the ECCL logging system) from a process which is not itsself ECCL enabled (ie not built using the ECCL classes). You may use this to generate logging from shell scripts or from Java servlets etc.

The tool requires at least two arguments:
'-Name XXX' specifies the name under which the message is to be logged and
'-Mesg XXX' specifies the content of the message to be logged.
The optional '-Mode XXX' argument specifies the type of log to be generated (one of Audit, Debug, Warn, Error or Alert) and defaults to generating a 'Warn' log.

The Terminate command line tool

The Terminate command line tool provides a mechanism to shut down an ECCL host. This tool contacts a Command server and tells it to shut down all it's local client process and then shut itsself down.
Each client of the Command server is given thirty seconds to shut down gracefully, and if it has not shut down when this period is over, the Command server is free to kill it.
You can expect Command servers to have shut down within forty seconds of the Terminate command being run.

You may use '-CommandHost' and '-CommandName' to specify a Command server to contact, otherwise the default local Command server is contacted (or if there is no local server, any available Command server on the local network is contacted).

If you wish to terminate everything in a cluster, you may use the '-CommandName' argument to specify the name of the 'Control' server of the cluster rather than the 'Command' server of an individual host. In this case the tool will contact the Control server, and the Control server will in turn send a terminate message to each Command server in the cluster, before closing down itsself.

*/ #ifndef INCLUDED_ECCL_H #define INCLUDED_ECCL_H #import #import #import #import #import #import #import #import #import #endif