prelude-client
Creating a Prelude Client
In order to send or to read data from a Prelude collector (prelude-manager),
you will need to create a #prelude_client_t object. This object will be necessary
for most of the work you are going to do with prelude.
Creating the client
int ret;
prelude_client_t *client;
ret = prelude_client_new(&client, "my-analyzer");
if ( ! client ) {
prelude_perror(ret, "Unable to create a prelude client object");
return -1;
}
This will create a new client object, whose default profile is my-analyzer.
This default profile might be overriden using the --prelude --profile profile_name option on your
command line as parsed by prelude_init().
Additionally, prelude specific option might be overriden using a Prelude specific configuration file,
like the template file created within each profile, or a configuration file specified using
prelude_client_set_config_filename() before prelude_client_start() is called.
The default required permission for the created client are set to PRELUDE_CONNECTION_PERMISSION_IDMEF_WRITE
and PRELUDE_CONNECTION_PERMISSION_ADMIN_READ, which mean the client will reject any certificate where
permission are set to anything less than this. You can change the default required permission using the
prelude_client_set_required_permission() function.
As an example, if you want to create a client that will read alert from a Manager, and accept administrative
option request you should use:
prelude_client_set_required_permission(client, PRELUDE_CONNECTION_PERMISSION_IDMEF_READ|PRELUDE_CONNECTION_PERMISSION_ADMIN_WRITE);
Once the client is created and you have everything setup, you will need to start your client.
The prelude_client_start() function is responsible for this, and will trigger the connection to
the configured manager, and send the initial client heartbeat.
ret = prelude_client_start(client);
if ( ret < 0 ) {
prelude_log(ret, "Unable to start prelude client");
return -1;
}
Additionally, it is possible to set additional client flags, however, you should be careful
since some of theses flags (marked asynchronous) will result in creating an internal thread,
which should only be done after an eventual fork of the program since threads are not copied
accross a fork call.
The prelude library will also register an internal timer in order to send heartbeat message at
the defined interval. Timer registered by the library itself or by the program will either be called
automatically if the #PRELUDE_CLIENT_FLAGS_ASYNC_TIMER flags is set, otherwise, the program is responsible
for calling the prelude_timer_wake_up() function every second from it's main loop, in order to check the
registered timer.
#PRELUDE_CLIENT_FLAGS_CONNECT - Used for a client to connect to a manager (this is the default).
#PRELUDE_CLIENT_FLAGS_HEARTBEAT - Used for client to send heartbeat (this is the default).
#PRELUDE_CLIENT_FLAGS_ASYNC_SEND - Used if you want message to be sent asynchronously.
#PRELUDE_CLIENT_FLAGS_ASYNC_TIMER - Used if you want timer to be automatically called from the asynchronous thread.
See #prelude_client_flags_t for a list of available flags.
ret = prelude_client_set_flags(client, PRELUDE_CLIENT_FLAGS_ASYNC_SEND|PRELUDE_CLIENT_FLAGS_ASYNC_TIMER);
if ( ret < 0 ) {
fprintf(stderr, "Unable to set asynchronous send and timer.\n");
return -1;
}
Sending IDMEF message
For documentation on how to create IDMEF message, please see #idmef_message_t
or #idmef_path_t.
Once you created and IDMEF message, you should use the prelude_client_send_idmef() function
in order to send it to the collector you are connected to.
prelude_client_send_idmef(client, idmef);
Destroying the client
In case the analyzer you are developing is not a persistant analyzer (meaning an
analyzer that is not supposed to exit), it is important that you call the prelude_client_destroy()
function prior to exiting. This function have the side effect of sending an heartbeat to the remote
manager, as well as an information regarding the analyzer state.
This state information is important since an analyzer not reporting a successful exit status,
or an analyzer which stop sending heartbeat at all will be reported as having a problem.
PRELUDE_CLIENT_STATUS_EXIT_SUCCESS - Exiting the sensor is the expected behavior.
PRELUDE_CLIENT_STATUS_EXIT_FAILED - There is something wrong going on, notice the security analyst.
prelude_client_destroy(client, PRELUDE_CLIENT_STATUS_EXIT_SUCCESS);
As a side note, please remember that a persistant sensor should never use this function
(except maybe if it is working in batch mode), unless it want to report the
PRELUDE_CLIENT_STATUS_EXIT_FAILED exit status. This is also the case if your persistant sensor
is interrupted by a signal.
#idmef_message_t
#idmef_path_t
@PRELUDE_CLIENT_EXIT_STATUS_SUCCESS:
@PRELUDE_CLIENT_EXIT_STATUS_FAILURE:
@PRELUDE_CLIENT_FLAGS_ASYNC_SEND:
@PRELUDE_CLIENT_FLAGS_ASYNC_TIMER:
@PRELUDE_CLIENT_FLAGS_HEARTBEAT:
@PRELUDE_CLIENT_FLAGS_CONNECT:
@client:
@Returns:
@client:
@pool:
@client:
@Returns:
@client:
@Returns:
@client:
@Returns:
@client:
@profile:
@Returns:
@client:
@Returns:
@client:
@Returns:
@client:
@permission:
@client:
@Returns:
@client:
@msg:
@client:
@cb:
@client:
@msg:
@client:
@status:
@client:
@flags:
@Returns:
@client:
@filename:
@Returns:
@client:
@Returns:
@error:
@Returns:
@client:
@Returns:
@client:
@msgbuf:
@Returns:
@client:
@msg:
@msgbuf:
@Returns:
@client:
@Returns:
@client: