This chapter covers the C header files used to send and retrieve information from the alert collector server. These files are found in the source/common directory under the directory you chose for the toolkit installation, if you have a version where source was provided.
This section is intended to provide enough information for you to be able to write your own interfaces to the alert collector server should you wish to do so.
Please note: this chapter is a work in progress, that was begun after the final build was produced when I realised not everyone may want to wade through the source code to implement theit own interfaces; and is not 100% accurate yet.
If you do not read this section any alert forwarding or alert monitoring implementations you write yourself will not work.
The message passing between the client and server programs is written using a rather lazy, but very easy to manage way. It uses the new-line character to indicate the end of a message buffer in both directions.
What does this mean to you if you are going to write your own alert forwarding or alert monitoring tools ?
The alert server collector program, and all the clients (aler generators and
monitoring tools, including the java gui) expect any embeded new-line
characters that are part of the data to be translated to the ^ (hat) symbol
before they are sent. The alert server and all my supplied utilities convert
the ^ back to a new line when they have recieved the entire data block.
You MUST follow the same convention.
If you are writing your interfaces in C you can use the supplied functions
transalate_nl_to_hat(char * buffer,int maxlen)
translate_hat_to_nl(char * buffer,int maxlen)
in the shared_utils.c file (refer to how I use this, shared_utils.o compiled
seperately and linked in to those programs that need the procedures).
You may also want to make use of the
pad_header_fields( common_header_def *buf)
routine, as all header fields are expected to be space padded
at the end.
The version.h file contains the version of the application that you have been shipped. Whatever interfaces you write must use the same version number, whether sourced from this file or coded yourself (preferably sourced from this file as other header files refer to this file also).
The version information is checked by the alert server process. The reason for this may not be apparent in this initial release of the server, but in other applications I have written, and eventually in this one, different branching logic can be used in the server depending on the client version to allow older clients to continue to work as upgrades are slowly rolled out to newer versions.
The version.h file just contains the version number. It is listed below.
#ifndef VERSION_H #define VERSION_H char application_version[] = "1.0.2"; #endif |
The constants.h file contains the record length definitions for some of the key data fields. Do NOT change any values here without recompiling all application programs as the record length constants are used extensively within the application code.
The supplied java GUI will not function correctly if some of these are changed, as it's written in java it doesn't use this constants file so will only work if the default supplied values are used.
The contents of constants.h is listed here, the use of the constants is explained below the listing.
#ifndef ALERTSERV_CONSTANTS #define ALERTSERV_CONSTANTS #define MAX_ASRV_REMOTEHOST_DATA_LEN 100 #define MAX_ASRV_CONSOLE_DATA_LEN 4096 #define MAX_ASRV_IO_BUFFSIZE 8192 #define MAX_ASRV_LEN_STR 4 #define MAX_ASRV_DATE_LEN 14 #define ASRV_PRODUCT_ID_LEN 14 #define ASRV_PRODUCT_VERSION_LEN 10 #define MAX_ASRV_HOSTNAME_LEN 15 #define MAX_ASRV_KEY_LEN 14 #define MAX_ASRV_OPT_DATA 29 #define ASRV_MAX_CONSOLE_LINE_LEN 127 #include "version.h" #endif |
| MAX_ASRV_REMOTEHOST_DATA_LEN |
This is the maximum data length that can be passed in
the datastr field of the API message header block in a
request to the alert server process. This is used to provide additional information to the alert server for the command it is being requested to process. What is passed in this field is dependant upon the request type in the message header. |
| MAX_ASRV_CONSOLE_DATA_LEN |
This is the maximimum size of the data area passed from
the alert server process to any monitoring
applications. This should not need to be changed. In an alert retrieve request the alert server process will fit as many lines of display data as possible in this area in a reply to the retrieve request, should not all data fit in one reply block the server process will send additional reply blocks as discussed later on. Using the defaults 32 alerts can be passed in this default size which should be adequate, at worst there will never be more that two blocks returned in a reply for a full 50 alerts. Warning: never increase this to the point where the the data area and header areas combined will exceed MAX_ASRV_IO_BUFFSIZE or you will encounter problems. |
| MAX_ASRV_IO_BUFFSIZE |
This is the maximum amount of data that will be read or
written by the server in a single IO. This is currently
sufficient at 8192 to handle all requests with the
exception of alert retrieval requests from monitoring
applications (which will be random sizes so not
possible to calculate anyway). It is strongly recomended that this be left as is. Do not make it smaller as it has been sized so all requests to the alert server come in a single block and the alert server expects that to be the case. |
| MAX_ASRV_LEN_STR |
In various headers passed back and forth between the
applications there may be variable length data in the
buffer fields. To indicate the length of the data there
is a string field containing the length of the
data as an ascii string number. This value is used to control the size of the string field containing the number, and used by programs that use the value of the number to avoid overrunning. This is set to 4, allowing a maximum value of "9999". As this is larger than any buffer sizes used it should not need to be changed. |
| MAX_ASRV_DATE_LEN |
This controls the size of the field used to record date
information. It allows for YYYYMMDD HH:MM with the
set size of 14, and should not need to be changed. Note: this also controls the length of the date field displays on monitoring screens, changing this will affect the display of alerts. Note2: The supplied java GUI will not function correctly if this is changed. |
| ASRV_PRODUCT_ID_LEN |
The length of the header field entry for the product
identifier. This should not be changed unless you are
creating your own alert retrieval application and use a
product name of greater than 14 bytes for it. The product field is used by the alert server to identify what type of client is communicating with it, if you write your own client with its own product identifier you will also have to change the alert server code to cope with it. |
| ASRV_PRODUCT_VERSION_LEN | This is the length of all fields that pass a product version number string. The current value should not need to be changed. |
| MAX_ASRV_HOSTNAME_LEN |
The maximum length that will be used to pass the
hostname that raised an alert back and forth. While
hostnames can be 255 bytes I don't know of anyone that
uses that size. If your site uses hostnames larger than this and don't want them truncated then you will need to increase this and recompile all the programs. Note: this also controls the length of the date field displays on monitoring screens, changing this will affect the display of alerts. Note2: The supplied java GUI will not function correctly if this is changed. |
| MAX_ASRV_KEY_LEN |
The maximum length to be allowed for the unique alert
key field passed to and recorded by the alert
server. Note: this also controls the length of the date field displays on monitoring screens, changing this will affect the display of alerts. Note2: The supplied java GUI will not function correctly if this is changed. |
| MAX_ASRV_OPT_DATA |
This defines the length of a field used to pass
optional data to the alert server. Optional data used
is request specific and covered in the function table
toward the end of this chapter. You should not change the default value here. |
| ASRV_MAX_CONSOLE_LINE_LEN |
The maximum line length returned for each alert display
when an alert retrieval request is made from a
monitoring program. Note: this also controls the length of the date field displays on monitoring screens, changing this will affect the display of alerts. Note2: The supplied java GUI will not function correctly if this is changed. |
The shared_api_header.h defined the common format message header that must be at the start of every message sent to the alert server process. The alert server process will sanity check this header and if a valid header is not found in a request it recieves the entire message block will be discarded. This prevents problems with the server when it recieves unexpected/unintended connections to it such as during penetration testing against all listening ports (or me telneting to it for testing).
All fields must be present, and legal, in any message sent to the
alert server process. All fields must be padded with trailing
spaces if they are shorter than the field length
The header structure is listed below, with the fields
described after the listing.
#ifndef ALERTSERV_CONSTANTS
#include "../common/constants.h"
#endif
#ifndef SHARED_API_HEADER
#define SHARED_API_HEADER
/* ------------------------------------------------------
common_message_header
Expected to be present in every data packet sent to
this server.
DO NOT MOVE productid FROM THE FIRST POSITION.
The productid is used for byte addressing the structure
throughout the code, so must remain the first element
and must be char.
------------------------------------------------------ */
typedef struct {
/* Source identification */
char productid[ASRV_PRODUCT_ID_LEN+1]; /* product name */
char version[ASRV_PRODUCT_VERSION_LEN+1]; /* product version */
char hostname[MAX_ASRV_HOSTNAME_LEN+1]; /* ipaddr allowed if necessary */
char unique_key[MAX_ASRV_KEY_LEN+1]; /* what the source identifies the msg as */
char response_port[6]; /* tcpip port for any responses, if 0 allow none or use request port */
char messagetype[2]; /* source dependant */
char expect_reply; /* Y=yes, N=no */
char source_date_time[MAX_ASRV_DATE_LEN+1]; /* date and time of event YYYYMMDD HH:MM + null */
} common_header_def;
#endif
|
The fields defined in the common header are as follows.
| productid |
This field is provided by the application making the
request and must identify the type of application that
is making the request. The value provided must match a known productid coded in the alert server, as it bases the processing of the request/reply upon the productid making the request to allow for special handling as needed. |
| version | Is the version of the productid making the request, passing a version idetifier allows the alert server process to be coded in a way that supports older versions of the product as well as new releases. |
| hostname |
Caution this is productid dependant. 99.99% of the time this will be the hostname of the machine requesting an alert be raised or cancelled (from an alert forwarding application). The exception to this rule is when the request is passed from an alert monitoring application for a request to change the state of an alert (delete/acknowledge) in which case it will be the name of the machine that raised the alert rather than the name of the machine the monitoring application is running on. The hostname and unique_key pair uniquely identify an alert. |
| unique_key |
This is a key tag assigned to an alert. This key is
used to add, acknowledge, delete or otherwise manage an
alert and should be unique for the event or application
being managed. The hostname and unique_key pair uniquely identify an alert. |
| response_port |
This is reserved for future use. At some point I will
alter the application to send unsolicited state changes
to applications down a port they select. In the present implementation this must always be 0 (zero) to indicate the reply is to return to the requesting port. It is only used by the alert server process. |
| messagetype |
One of the more important fields. This
identifies the type of command or reponse that is
contained in the message block. Available commands that can be issued, and reponses that may be returned are listed in the function table toward the end of this chapter. |
| expect_reply | This field may be either Y or N and indicates whether the requesting client expects a response from the alert server process for the request it has issued. If Y then an appropriate response will be returned to the client, if N then no response will be returned to the client. |
| source_date_time | The date and time the request was issued/created on the clients machine. This should be in YYYYMMDD HH:MM format. While thsi field is not sanity checked any alert forwarding tools you write for your own site should ensure the date and time provided are correct as this is the date and time that will be displayed for the alert on alert monitoring terminals. |
The alertserver_api_def.h file defines the format of the messages that
are expected to be recieved by the alert server. Messages not following this
format should be discarded by the alert server.
The key thing to note here is that it sources in the shared_api_header.h file
discussed above, you need to be aware of whats in the header to send a request
to the alert server process so review that if you have not already done so.
Below is the contents of the alertserver_api_def.h file. A description of the fields follows the listing.
#ifndef SHARED_API_HEADER
#include "../common/shared_api_header.h"
#endif
#ifndef ALERTSERVER_API
#define ALERTSERVER_API
/* ------------------------------------------------------
message_data_def
The structure used to pass events between a remote
host we are manageing. Incoming is whan an event on the
remote server changes, outgoing is we are requesting
the remote server take actions on our behalf.
------------------------------------------------------ */
typedef struct {
common_header_def msg_header;
/* Function identifiers in header msgtype field */
/* message type, indicates what the message is...
from a remote host to central server...
AC=critical alert,
AW=warning alert,
AK=alert-kill(delete/resolved)
KA=alert-acknowledge from remote server
IO=info only
LO=log only (not displayed to operators)
from central server to remote host
KA=alert acknowledged on central server
CM=command to execute provided for remote application
RF=refresh alerts to me/central-server (only on manual
command or server restart for each server we think we
have old entries stored for).
--=ACK of recieved message, no data
from console app to server
RC=remote command (not implemented)
AC=acknowledge alert
AD=delete alert
KK=delete alerts up to one identified in msg_header
SL=show list of alerts
SD=show details of an alert
from server to console app
DF=display buffer, more data follows
DB=display buffer, final data buffer
DS=display buffer of show details request, single data buffer
(DS added so java GUI can distinguish show details response in socket read thread
from other response types)
DE=display error, no more data follows
INTERNAL SERVER USE
DD=delete entry from table on next compress
*/
/* data string
for an incoming message this could be message text
for an outgoing (from central server) a command
*/
char sourcedatetime[15]; /* YYYYMMDD HH:MM */
char datapersists; /* Y=record kept after remote server disconnects,
N=all records from connection deleted when host disconnects
Note: Y should only be used by the command line tool that
connects, posts an alert and stops again. For servers
that are always expected to be running use N.
*/
char datastrlen[MAX_ASRV_LEN_STR+1]; /* Length of the data in datastr */
char datastr[MAX_ASRV_REMOTEHOST_DATA_LEN+1]; /* The data */
/* optional data
this is dependant upon source product, and may be
ignored by the central server
*/
char optdata[MAX_ASRV_OPT_DATA+1];
char NL; /* new line byte */
} message_data_def;
#endif
|
The fields in this definition, excluding the fields in the header which were dicussed in the previous section, are described below.
| sourcedatetime |
Oops, a bug. This is not used. Any datetime information
required is retrieved from the message header. Reserved for future use (re-use). |
| datapersists |
This may be Y or N. Y is intended for use by my command line raise_alert tool which connects, writes the request, and disconnects again. It allows the alert to remain valid after the connection has terminated. N is what would normally be used by tools or applications that connect directly to the alert server process during their life cycle. At the time the client diconnects all alerts still active for that client are automatically deleted. An example of that would be my job scheduler application, it raises alerts for various errors, and cancels them automatically when they are resolved, and does so across a permanet connection to the alert server process. When the scheduler is stopped, whether to resolve a problem or for a server shutdown, it is pointless to keep alerts for an application that is not running so the alerts are automatically cleaned up when the session terminates. |
| datastrlen | This field contains the length of the valid data in the datastr field following. The length is to be stored as a string, not as a binary number. |
| datastr | The data associated with the request being sent to the allert collector process. This is request dependant. See the funtion table at the end of this document for what may be placed here. |
| optdata | Any optional data to be provided to the server to enable it to correctly process the request. Use of this field is productid/version specific. |
| NL | A placeholder for the newline character that is used to terminate each data buffer block. |
The console_api_def.h file contains the data definition
that will be sent to alert monitoring programs in response to
any data retrieval requests.
It will also be sent to any alert monitoring programs
on completion of command requests to provide a refreshed list of
alerts, on the assumption the command they issued changed the alert
display in some way (unless the reply_expected was set to N).
Note that it sources in the shared_api_header.h file
discussed earlier, you need to be aware of whats in the header to send a request
to the alert server process so review that if you have not already done so.
The fields sent in a response to an alert monitoring application
are discussed here, with the exception of the common header fields that have
been previously discussed.
The definitions in the console_api_def.h file are listed below, the
field descriptions are after the listing.
#ifndef SHARED_API_HEADER
#include "../common/shared_api_header.h"
#endif
#ifndef CONSOLE_API
#define CONSOLE_API
/* ------------------------------------------------------
console_io_data_def
The structure used to pass events between a console
application and this server.
------------------------------------------------------ */
typedef struct {
/* Source identification of message in case commands to
be issued back to it from the console. */
common_header_def msg_header;
/* Function identifiers in header msgtype field */
/* Function identifiers, what to do with the message
--> to console
DF=display buffer, more data follows
DB=display buffer, last data buffer
DE=displayable error buffer, no more data
DS=display response to show details, single buffer
--=acknowledgement only, no action needed
<-- from console
RC=remote command
AC=acknowledge alert
AD=delete alert
KK=delete all displayed (up to one in last entry position)
SL=show list (produce alert list for client)
SD=show details (for selected alert)
*/
/* data string
--> to console, display buffers
<-- from console, commands
*/
char datastrlen[MAX_ASRV_LEN_STR+1]; /* n bytes + null */
char datastr[MAX_ASRV_CONSOLE_DATA_LEN+1]; /* n + null */
char NL; /* new line byte */
} console_io_data_def;
#endif
|
| datastrlen | This field contains the length of the valid data in the datastr field following. The length is to be stored as a string, not as a binary number. |
| datastr | Will in the response contain a list of current alerts known to the allert collector process. This can be an initial, continuation of final display of the alert listing; the type determined by the msgtype code in the header block. |
| NL | A placeholder for the newline character that is used to terminate each data buffer block. |
The below values are legal for the alert collector process to manage as of the time this build was released.
These are the alert forwarding productids at the time this alert toolkit was
shipped.
The GENALERT can probably be reused by any applications you code
youself however I would recomend creating your own product id for any in-house
alert generators and updating the procedure message_from_forwarding_application
in the alert server code to recognise it as an alert forwarder, and write any
customised handling for it.
These are the productids that will be recognised as alert monitoring tools,
that is tools that will be permitted to request the entire list of alerts
for display.
They allow for a fairly generic customisation of what is returned by the server
to suit your requirements.
If the generic CONSOLE, CONSOLEnn and CONSOLEnn_nn don't meet your requirements
you can create your own productid. You will need to register it in the alert
server process code in procedure message_from_console_application so
it is recognised as an alert monitoring application and
write your customised handling for it.
The Command entry is the two byte request that needs to be placed in the msgtype field of the header block for the request. You must ensure you fully populate all fileds in the header block or your request will be discarded.
These command codes used in this way can only be used by alert forwarding programs. They may have different meaning for other application types that communicate with the alert collector process.
For alert forwarding requests, completely apart from remembering that all header fields must be set for the alert to be processed, the ones to take special note of are
| Command | Description and supported data |
| AC |
Requests the alert server process to record this event
as a critical alert. The datastr field of the alertserver_api.h definition must contain the alert text, the datastrlen field must be set to the length of the valid data in the datastr field. |
| AW |
Requests the alert server process to record this event
as a warning alert. The datastr field of the alertserver_api.h definition must contain the alert text, the datastrlen field must be set to the length of the valid data in the datastr field. |
| AK |
Requests the alert server cancel/delete an existing
alert if one is found to match the heade fields. The
match is done on hostname and unique_key from the
message header. The datastr field of the alertserver_api.h definition may contain optional text to indicate why the alert has been cancelled, if so the datastrlen field must be set to the length of the valid data in the datastr field. |
| KA |
Requests that the alert matching the hostname and
unique_key pair in the message header be changed from
its current state to an acknowlegded state. Not generally used from alert forwarding tasks, but it is possible if you wish to do so, for example if you have an automation task that has kicked in it can acknowledge the alert automatically beofre starting recovery. |
| KH |
Asks the alert collector server to delete all alerts it
knows about for the hostname in the message header. This will generally only be used as part of a machines shutdown rc processing as if a server is supposed to be shutdown there is no point in the alert collector tracking alerts for it. A rc script would generally clear all the alerts for the host then write a scheduled shutdown warning event so eveybody knows it's deliberately down. The unique_key field is not used in processing this request so may be set to any value. |
| IO |
Requests the alert server process to record this event
as a information only event. The datastr field of the alertserver_api.h definition must contain the alert text, the datastrlen field must be set to the length of the valid data in the datastr field. |
| LO |
Requests the alert server process to record this event
as a log only event. The datastr field of the alertserver_api.h definition must contain the alert text, the datastrlen field must be set to the length of the valid data in the datastr field. Note: log only messages are never displayed to operators or managed further by the alert server process so the unique_key can be pretty much anything in this case. You should try to make it meaningfull as the only point in writing a log only message is if you intend to review the logs. |
Making requests from console/alert-monitoring programs to the alert server process is fairly straight-forward. All the information required is passed in the api header block, there is no need to provide any additional information.
One key thing to note is that the message header sent by a alert
monitoring application must set the hostname field to the value used by
the alert it is trying to issue a command for in all cases except for the SL
command.
Remeber that the alert server process manages the alerts using a key of
hostname and unique_key pairs based on the server that generated an alert, so
to issue a command against the alert you must use the hostname of the machine
that generated the alert, not the name of the machine you are running
the monitoring application on, for a command to match.
You will find this useage self explainatory if you have ever used the vt100 interface.
| Command | Description and supported data |
| RC | Remote command request. This has not yet been implemented so don't use this. |
| AC |
Requests the alert server process to change the state
of the alert matching the hostname and unique_key field
in the header to an acknowledged state. There is no data needed in the request other than a valid header block. Note: your console applications should be coded to not permit the acknowledgement of information only alerts. |
| AD |
Requests the alert server process to delete
the alert matching the hostname and unique_key
field. There is no data needed in the request other than a valid header block. |
| KK |
Requests the alert server to delete all alerts
until, and including, the alert matching the
hostname and unique_key fields set in the header
block. Usefull for tmes you have a screen full of alerts, and you know thay are being fixed, so you can safely delete the lot. |
| SL |
This requests the server to return a list of alerts to
the requesting client, as a list of lines suitable for
display. As a full lost of alerts is requested the hostname and unique_key fields do not need to be set for this request. This may require more than one response buffer sent to the requesting client, any client you write should be able to handle this by checking the response code to each reply buffer as documented in the response function code section below. The response is suitable for display on a dumb terminal (after you have done the ^ to NL processing discussed right at the beginning ofthe chapter). I normally reprocess this in my client code for flashy effects & colours etc depending upon client type. |
| SD |
This requests the server to respond with detailed
information on the alert described by the hostname and
unique_key fields in the message header. The response is suitable for display on a dumb terminal (after you have done the ^ to NL processing discussed right at the beginning ofthe chapter). Note: the response to this is a DS message type (covered below in the response code table) rather than a normal DB message type response for a displayable buffer. |
These are the response codes applications can expect in the msgtype field of the header, in response to a request they have made.
Alert forwarders generally would have the response_expected field set to N. For those that do have it set to Y the only msgtype value returned will be -- (double minus) to acknowledge reciept of the alert, the rest of the data buffer will be undefined and should not be processed by the client.
The monitoring programs do not necessarily need to get a response to requests
they send unless they are display requests.
I personally, for my alert monitoring applications, send any command that will
change the state of an alert (acknowledge/delete etc) as a request that has the
expect_reply field in the header set to N, then follow it with
a request to send them a new list of alerts. This updates the display
immediately for the user requesting the change without having to have a lot of
logic in the client to change the display line of the alert they were
affecting. It's simple and less likely to break.
Where responses are expected you need to be aware that a reponse may be sent in
multiple response buffers, your clients need to be able to handle this.
The responde codes to console applications are listed below, along with any
actions your clients need to take.
|
Response Code |
Description and relevant information |
| DB |
A display buffer has been provided. After you translate
the ^ characters to new-line characters the datastr
area for datastrlen is suitable for displaying on a
dumb terminal or printer (or to be processed by
scripts). It is the final block of data, there is no more data to follow (see DF below). |
| DE | A display buffer has been provided with an error message. The command sent to the alert server process failed !. After you translate the ^ characters to new-line characters the datastr area for datastrlen is suitable for displaying on a dumb terminal or printer. |
| DF |
A display buffer has been provided. It is only a
partial response. There is more data for the client
to read before the response is complete. You should bufferthe data and read the rest of the responses until you have an entire data block before processing the reply. You must keep reading replies until you recieve a DB response, or the alert server may block on writing the responses to your clieny (may hang). After you translate the ^ characters to new-line characters for the entire reply the data is suitable for displaying on a dumb terminal or printer. Note: at the time of shipping the only multibuffer response is for a display of all alerts, the alert server will only send complete lines in each response buffer (no partial lines) so if your client is just displaying the lines it can display them directly from the datastr area for datastrlen as each buffer is read. |
| DS |
The DS message response indicates, as for a DB,
that a displayable buffer (once ^ is converted to
new-line) has been recieved. vt100 consoles should just
display it. DS is used as the response code for all show alert detail requests. While it is in effect a displayable buffer DS is used instead of DB for a show details response specifically so my java gui can distinguish it from a normal display response and popup a new window. |
The ability for the alert server to update clients with changing event states in real-time using unsolicited messages sent from the alert collector server has not yet been implemented.
One less table for you to worry about, for now anyway.