-
Notifications
You must be signed in to change notification settings - Fork 2
/
ECCL.h
214 lines (194 loc) · 10.3 KB
/
ECCL.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
/** Enterprise Control Configuration and Logging
Copyright (C) 2013 Free Software Foundation, Inc.
Written by: Richard Frith-Macdonald <[email protected]>
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.
<chapter>
<p>The index below lists the major components of the ECCL
documentation.<br/></p>
<index type="title" scope="project" target="mainFrame" />
<section>
<heading>Enterprise Control Configuration and Logging</heading>
<p>
Classes and tools for building and administering 24*7
server processes for large scale software systems.
</p>
</section>
<section>
<heading>The Control command line tool</heading>
<p>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.
</p>
<p>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.
</p>
<p>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.
</p>
<p>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.<br />
This for instance allows all processes in a cluster to use a single
encryption key never stored on disk.<br />
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.<br />
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).
</p>
</section>
<section>
<heading>The Command command line tool</heading>
<p>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.
</p>
</section>
<section>
<heading>The Console command line tool</heading>
<p>Based around the [EcConsole] class, this process provides an
interactive command-line based interface for controlling the
entire system via the Control server.<br />
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:
</p>
User (or the ConsoleUser environment variable) specifies the
user for whom the tool is performing an action.<br />
Pass (or the ConsolePass environment variable) specifies the
password for the user login to the Control server.<br />
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).<br />
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.<br />
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.<br />
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.<br />
While waiting for a pattern to be matched, any messages received
by the Console process are provided as output (to STDOUT).<br />
Quiet (or the ConsoleQuiet environment variable) is a boolean
which, if true, will suppress any output while waiting for a
pattern to be matched.<br />
If the Control server cannot be contacted, the process exit status
is 10.<br />
If the Control server actively refuses the login, the exit status
is 11.<br />
NB. Command line arguments take precedence over environment variables
even if the command line argument is an empty string.<br />
A couple of extra variables alter the format of output as follows:<br />
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.<br />
Prompt (or the ConsolePrompt environment variable) can be set to NO
to suppress the normal prompt line at the end of each message.
</section>
<section>
<heading>The AlarmTool command line tool</heading>
<p>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).<br />
You may use this to generate logging from shell scripts
or from Java servlets etc.
</p>
<p>The tool requires at least four (usually six) arguments:<br />
'-Cause NN' the probable cause of the alarm (type of problem).<br />
'-Component NN' the component which raised the alarm.<br />
'-Problem NN' the specific problem which raised the alarm.<br />
'-Process NN' the name of the process which raised the alarm.<br />
'-Repair NN' a proposed repair action to fix the issue.<br />
'-Severity NN' the severity of the problem (defaults to 'cleared',
in which case the Repair action is not required).<br />
</p>
</section>
<section>
<heading>The LogTool command line tool</heading>
<p>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.
</p>
<p>The tool requires at least two arguments:<br />
'-Name XXX' specifies the name under which the message is to be logged
and<br />
'-Mesg XXX' specifies the content of the message to be logged.<br />
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.
</p>
</section>
<section>
<heading>The Terminate command line tool</heading>
<p>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.<br />
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.<br />
You can expect Command servers to have shut down within forty
seconds of the Terminate command being run.
</p>
<p>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).
</p>
<p>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.
</p>
</section>
</chapter>
*/
#ifndef INCLUDED_ECCL_H
#define INCLUDED_ECCL_H
#import <ECCL/EcAlarm.h>
#import <ECCL/EcAlarmDestination.h>
#import <ECCL/EcAlarmSinkSNMP.h>
#import <ECCL/EcAlerter.h>
#import <ECCL/EcBroadcastProxy.h>
#import <ECCL/EcHost.h>
#import <ECCL/EcLogger.h>
#import <ECCL/EcProcess.h>
#import <ECCL/EcUserDefaults.h>
#endif