libram-install(3) libram Reference libram-install(3) 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 connec- tions. 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 pro- cedure call based on onc/rpc. The server side of this rpc communicta- tion is implemented in libram-rpcserver, that can be linked to the analysis component. MODULES libram ships with the following modules: accept This is a dummy module, that does no analysis or modification, but always returns action_pass. deny This is a dummy module, that does no analysis or modification, but always returns action_block. record This is a module that records the data from the client and writes them to an output file in the format specified in libram- record - (5). The data in the file can be replayed using the ramc-replay(1) libram client. ipacl An acl list based on ip addresses, ports, and protocols rpc This is the module that offers remote procedure calls using onc/rpc. It comes with two libraries: libram - -rpc.so is the client side and offers the libram_module(3) api. libram-rpc- server.so is the server side, that needs to be added in the remote analysis software. See libram-rpcserver(3) for further details about how use the server side library. 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 addi- tional 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= The default installation directory for the libram modules is ${lib- dir}/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-=[yes|no] or --without- to enable or dis- able 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 avail- able. # ldconfig If the testsuite fails please have a look at the log file tests/test- suite.log. Under Linux with the global library search path, sometimes old versions of libram get used instead of the new compiled version. If the test- suite 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 cre- ate 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), boot- strap (to bootstrap the GNU autotools and build the configure and Make- files), and build where the actual build process is performed. $ mkdir source $ cd source $ git pull /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: - The documentation is generated automatically using robodoc. Since we want to install all documentation, the names for the man pages and html help files are generated from the source files, and we have to create corresponding Makefile.am files in the docs directory. 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 neces- sary 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 automati- cally updated. (The information of which documentation file is depen- dend 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 Sep 18, 2013 libram-install(3)