TABLE OF CONTENTS

libram/libram [ Generics ]

[ Top ] [ Generics ]

NAME

libram - remote analysis and modification library

SYNOPSIS

#include <libram.h>

DESCRIPTION

libram is a library for remote analysis and modification. libram does not contain any real analysis or filter components. But instead, it offers an extendable module interface where analysis and modification modules can be added. These modules are called backend modules. The modules need to be loaded befor they are used. Loading modules is performed with libram_load(3).

The interface allows both local and remote modules. Local modules can be implemented with shared libraries, that run within the process space of the calling process. Remote modules can run on separate machines using remote procedure calls.

To avoid network latencies in remote modules, libram is using a asynchronous mode by default. That means that libram can do libram calls, but does not have to wait for the result. Instead it can continue with useful work and collect the results later.

Local modules does not suffer network latency. Thus it is possible for them to return the analysis result immediate. To allow a uniform programming api for both synchronous and asynchronous modules. libram(3) contains a wrapper that makes synchronous modules behave asynchronous.

The libram client can negotiate the use of synchronous mode with libram_init(3). If the libram client sets the flag LIBRAM_SYNCHRONOUS in libram_init, it requests synchronous mode. If the backend does not support synchrnous mode, it clears this flag. The libram client has to check this flag after the call to libram_init(3) before switching to synchronous mode.

If the client wants to use asynchronous mode, the LIBRAM_SYNCHRONOUS should not be set. The backend can still set the LIBRAM_SYNCHRONOUS flag, but the client does not need to honor this flag, since libram is able to offer the asynchronous api to asynchronous backends. This is the wrapper that is mentioned above.

See libram-synchronous(3) for a description of synchronous api calls and libram-asynchronous(3) for a description of asynchronous api calls.

libram offers two different interfaces. The first interface makes use of structures defined in <libram-xdr.h>. This file is generated from the xdr representation of the communication protocol, and needs to include <rpc/rpc.h>.

The functions uses in this interface are:

To use this interface, inclusion of <libram-xdr.h> is necessary.

To avoid possible name conflicts with symbols defined in <rpc/rpc.h>. libram offers an alternative interface. The difference between these interfaces is, that the normal libram interface passed data in structures, that are defined in <libram-xdr.h>, and thus require <rpc/rpc.h>.

The second libram interface does not include <libram-xdr.h> and does not use the structures defined in <libram-xdr.h>, but splits the structures into components. The network related components are replaced with struct sockaddr * parameters. The data related parameters are passed in separate arguments.

The functions used in this second interface are:

The s stands for sockaddr or second interface.

Both interfaces use the libram_process(3) function to get the result in asynchronous mode.

The return value for libram_open(3), libram_data(3), libram_close(3), libram_sopen(3), libram_sdata(3), libram_sclose(3) and the function libram_process(3) for asynchronous request is a reply structure, see reply(3) for details. The reply structure is defined in <libram-xdr.h>. The functions can return special reply values to indicate errors:

To access the contents of the reply structure without including <libram-xdr.h> one can use the access function:

libram(3) also offers a simple callback managment framework that insert callbacks for pending replies on a callback list. The callback list is initialized with libram_cb_init(3) and freed with libram_cb_exit(3). libram_cb_register(3) is used to add callbacks to this list, while libram_cb_dispatch(3) activates the callbacks when a response is available. See libram-cb(3) for further details.

SEE ALSO

libram-install(3), libram_flags(3), libram_load(3), libram_init(3), libram_exit(3), libram_open(3), libram_data(3), libram_close(3), libram_sopen(3), libram_sdata(3), libram_sclose(3), libram_reply_get_action(3), libram_reply_get_id(3), libram_reply_get_processed(3), libram_reply_get_replace_direction(3), libram_reply_get_replace_len(3), libram_reply_get_replace_val(3), libram-synchronous(3), libram-asynchronous(3), libram-cb(3), reply(3)

libram/libram-asynchronous [ Generics ]

[ Top ] [ libram ] [ Generics ]

NAME

libram-asynchronous - asynchronous libram api

SYNOPSIS

#include <libram-xdr.h>
#include <libram.h>

DESCRIPTION

In asynchronous libram mode the result of the analysis process is not returned directly to the libram client. Since the analysis process might take some time, the client can do other useful work. Later, the client can check if a result from the backend module is available.

Aysynchronous mode is based on the select(2) system call. With select, one registers the possible input file descriptors. select(2) checks which file descriptors have data ready to be read and returns thes file descriptors allowing non blocking input processing.

To assist this programming model, libram_fdset(3) adds the libram internal file descriptors to a fd_set of reading file descriptors. This fd_set is used in select(2) to check of input to libram is ready to be processed.

If select(2) returns with file descriptors ready to be read, libram_process(3) checks if the libram internal file descriptors are among this set. If the input from the libram interal file descriptors has returned enough data for an analysis result, libram_process(3) also returns this analyis result with an non-NULL return value.

This result can be processed, and has to be freed later using libram_free(3).

If there are other file descriptors ready to be read, the libram client has to handle this input as well.

If the libram client does not want to implement an event loop based on select, the client can also call libram_wait(3) to wait for an analysis result. libram_wait(3) contains a timeout parameter, so the client can control how long to wait for a result.

If the client does not want to wait, it can eihter specify a timeout value of 0 or call libram_poll(3) with the same result.

EXAMPLE

#include <libram-xdr.h>
#include <libram.h>

int fd1, fd2, mfd;
ram_fh fh;
int flags = 0;
fd_set fds;
struct reply *result;

fh = libram_load(module, path);      // load module
....

if( libram_init(fh, connect, &flags) == NULL ) { // init module
  exit(1);
}

while( 1 ) {
  ....
  libram_open(fh, 0, &hdr, &payload); // do asynchronous call
  ...
  
  FD_ZERO(&fds);                      // clear fd_set
  FD_SET(fd1, &fds);                  // set other input fd
  
  fd2 = libram_fdset(fh, &fds);       // add libram fd, return libram max fd
  mfd = max(fd1, fd2) + 1;            // calculate max fd

  if (select(mfd, &fds, ...) > 0 ) {     // call select to get read fds
    result = libram_process(&fds);       // handle input on libram fds
    ...                                  // handle input on other fds
    if( LIBRAM_IS_VALID_REPLY(result) )  // check if result is valid
        libram_free(fh, result);         // and free result
  }

}
...
libram_exit(fh);

NOTES

The internal file descriptor can also be requesteted with libram_fd(3).

SEE ALSO

libram-install(3), libram_load(3), libram_init(3), libram_exit(3), libram_open(3), libram_data(3), libram_close(3), libram_flags(3), libram_fdset(3), libram_fd(3), libram_process(3), libram_wait(3), libram_poll(3), libram_free(3), libram-synchronous(3), select(2)

libram/libram-install [ Generics ]

[ Top ] [ libram ] [ Generics ]

NAME

libram-install - install instructions for libram

INSTALL INSTRUCTIONS FOR BUILDING LIBRAM

libram is a remote analysis and modification library.

libram is a framework to analye the payload data in tcp or udp connections. libram does not contain any real analysis or filter components. But instead, it offers the possibility to add analysis and modification modules, called backend modules.

libram is implemented as a library api instead of a network api. This allows the implementation of backend modules in form of a library, so that the analysis process can be run in the same process space as the callee.

To also offer network analysis modules, the libram library api can be also imlemented via remote procedure calls. libram offers a remote procedure call based on onc/rpc. The server side of this rpc communictation is implemented in libram-rpcserver, that can be linked to the analysis component.

MODULES

libram ships with the following modules:

REQUIREMENTS

The onc/rpc components depend on libraries offered by onc/rpc.

BUILDING LIBRAM

Building libram depends on wether you have the maintainer version or a distribution version.

Normally you should get the source code in distribution version where all required configure scripts and additional files are integrated. Contrary the maintainer version only consists input files for the GNU autoconf tools, and you thus need the GNU autoconf tools (and additional tools) installed.

BUILDING USING THE DISTRIBUTION VERSION

If you have the distribution version, configuring, building and installing libram is straitforward:

Unpack the distribution tar file libram-x.y.z.tar.gz and change to the libram-x.y.z directory: 

      $ gunzip -c libram-x.y.z.tar.gz | tar xvf -
      $ cd libram-x.y.z

Here you find the configure script to check your system and to generate Makefiles and other files. You can get an overview for the options on the configure script by using the --help option: 

      $ ./configure --help

To configure libram, run the configure script. You might use --prefix to change the installation prefix: 

      $ ./configure --prefix=<path to libram>

The default installation directory for the libram modules is ${libdir}/libram. To change this installation directory, specifiy the new directory with: 

      --with-moduledir=[PATH]  set path to module directory

If PATH does not begin with a / (i.e. a relative path), it is appended to ${libdir} resulting in an installation path ${libdir}/PATH. Once the software is configure, you can build it using make

The available modules can be enabled or disabled at configure time. Use: 

       --with-<module>=[yes|no] or --without-<module>

to enable or disable the module. 

      $ make

There is a test suite that you might run to check the compilation process: 

      $ make check

The last check is a test with valgrind for memory leaks. This check is only run, if valgrind can be found, else it is skipped.

If the check is successfull, the software is ready to be installed. Usually, this requires super user rights: 

      $ su -
      # make install

It might be necessary to run ldconfig to make the shared library available. 

      # ldconfig

If the testsuite fails please have a look at the log file tests/testsuite.log.

Under Linux with the global library search path, sometimes old versions of libram get used instead of the new compiled version. If the testsuite failes, please remove old versions of libram.so and the modules in the libram directory, e.g. /usr/local/lib/libram.so* and /usr/local/lib/libram/libram-*.

This might also be necessary, if all checks pass but the valgrind check fails.

BUILDING USING THE MAINTAINER VERSION

If you have the maintainer version, there are additional steps to create the software.

One reason why you want to use the maintainer version is that you checked out libram from its repository.

The build process uses three directories (you might also use only one directory, but keeping the directories seperate helps distinguishing the maintainer from the distribution version),

The three directories are called source (for the source code), bootstrap (to bootstrap the GNU autotools and build the configure and Makefiles), and build where the actual build process is performed. 

      $ mkdir source
      $ cd source
      $ git pull <URL-to-GIT-Repository>/libram

We build the bootstap directory, where we copy a link tree of the source directory with lndir: 

      $ mkdir bootstrap
      $ cd bootstap
      $ lndir ../source .

The next step is to call the GNU autoconf tools to create the dependend files. We use a customized bootstrap.sh shell script to perform this step, since we want to also generate additional files:

To perform this step, call 

      $ ./bootstrap.sh

Running this script generates all files necessary to configure libram.

Now, bootstrapping is finished, and we continue with the configuration step: 

      $ cd ..
      $ mkdir build
      $ cd build

From the build directory, we call the configure script in the bootstrap directory: 

      $ ../bootstrap/configure

From this step onwards, the procedure is the same like the procedure with the distribution version. E.g. you can now pass additional options to the configure script... 

      $ make
      $ make check
      $ su
      # make install

Using the maintainer version of libram, you can build a distribution version by running: 

      $ make dist

This creates a libram-x.y.z.tar.gz that contains all the files necessary to build the software.

It also contains the documentation, since this requires robodoc to be installed, and we don't want to require robodoc beeing installed for building libram.

Note: The documentation is only generated once. If you change the descriptions in the source files, the documentation is not automatically updated. (The information of which documentation file is dependend from which source file is missing).

To update the documentation, run 

      $ make doc

The documentation is always updated if you create a distribution using 

      $ make dist

SEE ALSO

libram(5)

libram/libram-synchronous [ Generics ]

[ Top ] [ libram ] [ Generics ]

NAME

libram-synchronous - synchronous libram api

SYNOPSIS

#include <libram-xdr.h>
#include <libram.h>

DESCRIPTION

In synchronous libram mode the result of the analysis process is returned directly to the libram client. Since the analysis process may take some time, the client blocks during this time.

The reply structures of the libram api calls has to be freed after use with libram_free(3).

Synchronous mode has to be negotiated with the backend. The libram client set the LIBRAM_SYNCHRONOUS in libram_init(3). If the backend module does not support synchronous mode, it clears the flag. The libram client has to check the flag returned from libram_init(3) before switching to synchronous mode.

EXAMPLE

#include <libram-xdr.h>
#include <libram.h>

ram_fh fh;
int flags = LIBRAM_SYNCHRONOUS;
struct reply *result;

fh = libram_init(module, path);
...
if( libram_init(fh, connect, &flags) == NULL ) {
    exit(0);
}
...
if( (flags & LIBRAM_SYNCHRONOUS) == 0 ) {
    exit(0);              // backend does not support synchronous mode
}

while ( 1 ) {
    result = libram_open(fh, 0, &hdr, &payload); // do synchronous call
    ...                                          // handle result
    libram_free(fh, result);                     // free result

    result = libram_data(fh, id, &payload);      // pass data to backend
    ,..                                          // handle result
    if( LIBRAM_IS_VALID_REPLY(result) )          // check if result is valid
        libram_free(fh, result);                 // and free result
    ...
}
...
libram_exit(fh);

SEE ALSO

libram-install(3), libram_load(3), libram_init(3), libram_exit(3), libram_open(3), libram_data(3), libram_close(3), libram_flags(3), libram_fdset(3), libram_fd(3), libram_process(3), libram_wait(3), libram_poll(3), libram_free(3), libram-asynchronous(3)

libram/libram_exit [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_exit - finalize libram

SYNOPSIS

int libram_exit(ram_fh fh)

DESCRIPTION

libram_exit finalizes the libram library. Memory allocated with libram_load(3) is freed.

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_load(3), libram_init(3), ram_fh(3), libram_module(3)

libram/libram_fd [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_fd - get filedescriptor used by libram backend

SYNOPSIS

int libram_fd(ram_fh fh)

DESCRIPTION

libram_fd is used to get the file descriptor used internally in libram.

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_process(3), libram_fdset(3), libram_wait(3), libram_poll(3), libram_free(3)

libram/libram_fdset [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_fdset - set filedescriptor used by libram backend to fdset

SYNOPSIS

int libram_fdset(ram_fh fh, fd_set *fds)

DESCRIPTION

libram_fdset is used to get the file descriptors used internally in libram. The file descriptor used is set in fds. libram_fdset returns the number of the highest filedescriptor set.

The fd_set is not cleared in libram_fdset. So it is save to pass an initialized fd_set to libram_fdset(3).

libram_fdset returns the internal file descriptor. This value can be used be the caller to caluclate the maximum file descriptor used by select(3).

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_fd(3), libram_process(3), libram_wait(3), libram_poll(3), libram_free(3)

libram/libram_free [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_free - free reply output structure

SYNOPSIS

void libram_free(ram_fh fh, struct reply *res)

DESCRIPTION

libram_free frees the reply structures returned by libram_process(3) and libram_wait(3).

ARGUMENTS

SEE ALSO

libram(3), libram_process(3), libram_fdset(3), libram_fd(3), libram_wait(3), libram_poll(3)

libram/libram_init [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_init - initalize libram module

SYNOPSIS

ram_fh libram_init(ram_fh fh, char *connect, int *flags)

DESCRIPTION

libram_init initalizes the libram library loaded with libram_load(3). The connect argument is used to pass additional arguments to the backend module. Since there is no fixed backend module, the data has to be passed as a string argument, similar to the connection strings used in odbc.

The connect string consists of value=key pairs, seperated by semicolon. The possible keys and values are documented in the manual sections for the particular backend module.

The caller can pass flags to the backend module, see libram_flags(3). The flags parameter is both a input and output parameter. Flags not understood by the client can be cleared, and the caller has to check if the client supports the flag.

Possible flags include the LIBRAM_SYNCHRONOUS flag, which is used to negitiate synchrounous mode. See libram(3) for a description of synchronous vs. asynchronous mode, and libram-synchronous(3) of libram-asynchronous(3) for the api description.

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_flags(3), libram-asynchronous(3), libram-synchronous(3) libram_load(3), libram_exit(3), ram_fh(3), libram_module(3)

libram/libram_load [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_load - load libram module to memory

SYNOPSIS

ram_fh libram_load(char *backend, char *path)

DESCRIPTION

libram_load loads a libram module to memory. The module name is specified in the backend parameter. The path argument gives the path to the directory conaining the backend modules. If path is NULL, the default backend directory set at configure time is used.

The module loaded with libram_load needs to be initialized with libram_init(3).

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_init(3), libram_exit(3), ram_fh(3), libram_module(3),

libram/libram_poll [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_poll - poll for result of backend module

SYNOPSIS

struct reply *libram_poll(ram_fh fh)

DESCRIPTION

libram_poll checks if a result is available and returns the reply. If no result is available, it returns NULL.

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_process(3), libram_fdset(3), libram_fd(3), libram_wait(3), libram_free(3)

libram/libram_process [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_process - process input on libram backend file descriptor

SYNOPSIS

struct reply* libram_process(ram_fh fh, fd_set *fds)

DESCRIPTION

libram_process handles input on the libram file descriptor. It checks if it's file descriptor is set in the fd_set fds and processes incoming data.

ARGUMENTS

RETURN

SEE ALSO

libram(3), libram_fdset(3), libram_fd(3), libram_wait(3), libram_poll(3), libram_free(3)

libram/libram_wait [ Functions ]

[ Top ] [ libram ] [ Functions ]

NAME

libram_wait - wait for processing of backend module

SYNOPSIS

struct reply *libram_wait(ram_fh fh, int timeout)

DESCRIPTION

libram_wait waits for the reply of a backend module. If no reply is available after the specified timeout, libram_wait returns NULL.

ARGUMENTS

RETURN

NOTES

Some modules will take several steps in collecting the result, Each step will use this timeout value. Thus the timeout value gives no upper limit for libram_wait(3).

SEE ALSO

libram(3), libram_process(3), libram_fdset(3), libram_fd(3), libram_poll(3), libram_free(3)